workly 0.1.0__tar.gz → 0.2.1__tar.gz

{workly-0.1.0 → workly-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workly
-Version: 0.1.0
+Version: 0.2.1
 Summary: Python SDK for Workly, the open-source HTTP task queue
 Keywords: task queue,background jobs,webhooks,http
 License-Expression: Apache-2.0
@@ -182,6 +182,36 @@ client.schedules.delete("nightly-report")  # with all its runs
 
 Runs are delivered with `Workly-Run-Id`, `Workly-Schedule` and `Workly-Scheduled-For` headers and the same signature, so `verify_signature` works unchanged.
 
+## Task groups
+
+A group tracks a set of tasks and enqueues a callback task once it's closed and they've all finished: a `POST` of the group's status and counts. See [Task groups](https://docs.workly.run/groups/). The callback goes to Workly's `_callbacks` queue unless it names a `queue`.
+
+```python
+from workly import Callback
+
+group = client.groups.create(
+    name="daily-stock-prices",
+    idempotency_key="stock-prices-2026-10-19",  # creating it again returns this group
+    # or a dict: {"url": "https://api.example.com/jobs/refresh-views"}
+    on_complete=Callback(url="https://api.example.com/jobs/refresh-views"),
+)
+for company in companies:
+    client.tasks.enqueue(
+        "stock-prices",
+        url="https://api.example.com/jobs/update-stock-price",
+        payload={"symbol": company.symbol},
+        group_id=group.id,
+    )
+client.groups.close(group.id)  # no more tasks; it completes once they've finished
+
+group = client.groups.get(group.id)
+print(group.status, group.total, group.succeeded, group.failed, group.remaining)
+for task in client.tasks.list(group_id=group.id, state="failed"):
+    print(task.id, task.last_error)
+for group in client.groups.list(name="daily-stock-prices", status="failed"):
+    print(group.id, group.finished_at)
+```
+
 ## Async
 
 `AsyncWorkly` has the same methods, as coroutines:

{workly-0.1.0 → workly-0.2.1}/README.md

@@ -162,6 +162,36 @@ client.schedules.delete("nightly-report")  # with all its runs
 
 Runs are delivered with `Workly-Run-Id`, `Workly-Schedule` and `Workly-Scheduled-For` headers and the same signature, so `verify_signature` works unchanged.
 
+## Task groups
+
+A group tracks a set of tasks and enqueues a callback task once it's closed and they've all finished: a `POST` of the group's status and counts. See [Task groups](https://docs.workly.run/groups/). The callback goes to Workly's `_callbacks` queue unless it names a `queue`.
+
+```python
+from workly import Callback
+
+group = client.groups.create(
+    name="daily-stock-prices",
+    idempotency_key="stock-prices-2026-10-19",  # creating it again returns this group
+    # or a dict: {"url": "https://api.example.com/jobs/refresh-views"}
+    on_complete=Callback(url="https://api.example.com/jobs/refresh-views"),
+)
+for company in companies:
+    client.tasks.enqueue(
+        "stock-prices",
+        url="https://api.example.com/jobs/update-stock-price",
+        payload={"symbol": company.symbol},
+        group_id=group.id,
+    )
+client.groups.close(group.id)  # no more tasks; it completes once they've finished
+
+group = client.groups.get(group.id)
+print(group.status, group.total, group.succeeded, group.failed, group.remaining)
+for task in client.tasks.list(group_id=group.id, state="failed"):
+    print(task.id, task.last_error)
+for group in client.groups.list(name="daily-stock-prices", status="failed"):
+    print(group.id, group.finished_at)
+```
+
 ## Async
 
 `AsyncWorkly` has the same methods, as coroutines:

{workly-0.1.0 → workly-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workly"
-version = "0.1.0"
+version = "0.2.1"
 description = "Python SDK for Workly, the open-source HTTP task queue"
 readme = "README.md"
 license = "Apache-2.0"

{workly-0.1.0 → workly-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "workly"
-version = "0.1.0"
+version = "0.2.1"
 description = "Python SDK for Workly, the open-source HTTP task queue"
 readme = "README.md"
 license = "Apache-2.0"

{workly-0.1.0 → workly-0.2.1}/src/workly/__init__.py

@@ -2,13 +2,14 @@
 
 from ._async_client import (
     AsyncAlerts,
+    AsyncGroups,
     AsyncQueues,
     AsyncRuns,
     AsyncSchedules,
     AsyncTasks,
     AsyncWorkly,
 )
-from ._client import Alerts, Queues, Runs, Schedules, Tasks, Workly
+from ._client import Alerts, Groups, Queues, Runs, Schedules, Tasks, Workly
 from ._errors import (
     APIConnectionError,
     APIError,
@@ -31,10 +32,15 @@ from ._models import (
     AlertChannelType,
     Attempt,
     AttemptOutcome,
+    Callback,
     CronPreview,
     Delivery,
     EnqueueResult,
     FailureGroup,
+    Group,
+    GroupCallback,
+    GroupPage,
+    GroupStatus,
     HTTPMethod,
     LastRun,
     MissedPolicy,
@@ -48,11 +54,13 @@ from ._models import (
     RunTrigger,
     Schedule,
     SkipReason,
+    SortOrder,
     Task,
     TaskPage,
+    TaskSort,
     TaskState,
 )
-from ._requests import TaskSpec, __version__
+from ._requests import CallbackDict, GroupCallbackSpec, TaskSpec, __version__
 from ._signing import sign, verify_signature
 
 __all__ = [
@@ -66,6 +74,7 @@ __all__ = [
     "AlertChannelType",
     "Alerts",
     "AsyncAlerts",
+    "AsyncGroups",
     "AsyncQueues",
     "AsyncRuns",
     "AsyncSchedules",
@@ -75,11 +84,19 @@ __all__ = [
     "AttemptOutcome",
     "AuthenticationError",
     "BadRequestError",
+    "Callback",
+    "CallbackDict",
     "ConflictError",
     "CronPreview",
     "Delivery",
     "EnqueueResult",
     "FailureGroup",
+    "Group",
+    "GroupCallback",
+    "GroupCallbackSpec",
+    "GroupPage",
+    "GroupStatus",
+    "Groups",
     "HTTPMethod",
     "LastRun",
     "MissedPolicy",
@@ -101,8 +118,10 @@ __all__ = [
     "Schedules",
     "SignatureVerificationError",
     "SkipReason",
+    "SortOrder",
     "Task",
     "TaskPage",
+    "TaskSort",
     "TaskSpec",
     "TaskState",
     "Tasks",

{workly-0.1.0 → workly-0.2.1}/src/workly/_async_client.py

@@ -17,10 +17,14 @@ from ._models import (
     AlertChannelList,
     AlertChannelType,
     Attempt,
+    Callback,
     CronPreview,
     Delivery,
     EnqueueResult,
     FailureGroup,
+    Group,
+    GroupPage,
+    GroupStatus,
     HTTPMethod,
     MissedPolicy,
     OverlapPolicy,
@@ -30,8 +34,10 @@ from ._models import (
     RunPage,
     RunState,
     Schedule,
+    SortOrder,
     Task,
     TaskPage,
+    TaskSort,
     TaskState,
 )
 
@@ -60,6 +66,7 @@ class AsyncWorkly:
         self._max_retries = max_retries
         self.queues = AsyncQueues(self)
         self.tasks = AsyncTasks(self)
+        self.groups = AsyncGroups(self)
         self.schedules = AsyncSchedules(self)
         self.runs = AsyncRuns(self)
         self.alerts = AsyncAlerts(self)
@@ -208,6 +215,7 @@ class AsyncTasks:
         idempotency_key: str | None = None,
         max_attempts: int | None = None,
         timeout_seconds: float | None = None,
+        group_id: str | None = None,
         traceparent: str | None = None,
     ) -> Task:
         """Enqueue a task to deliver to `url`.
@@ -215,7 +223,8 @@ class AsyncTasks:
         `payload` is sent as JSON; `body` as raw text (use one). The queue is
         created with default settings if it doesn't exist. If
         `idempotency_key` matches a task already in the queue, that task is
-        returned and nothing is enqueued.
+        returned and nothing is enqueued. With `group_id`, the task joins
+        that group, which must be open.
         """
         spec = {
             "url": url,
@@ -229,6 +238,7 @@ class AsyncTasks:
             "idempotency_key": idempotency_key,
             "max_attempts": max_attempts,
             "timeout_seconds": timeout_seconds,
+            "group_id": group_id,
         }
         return Task._from_json(await self._client._send(r.enqueue(queue, spec, traceparent)))
 
@@ -270,22 +280,33 @@ class AsyncTasks:
         *,
         queue: str | None = None,
         state: TaskState | None = None,
+        group_id: str | None = None,
         idempotency_key: str | None = None,
         last_error: str | None = None,
         created_after: datetime | None = None,
         created_before: datetime | None = None,
+        sort: TaskSort | None = None,
+        order: SortOrder | None = None,
         page_size: int | None = None,
     ) -> AsyncIterator[Task]:
-        """Tasks matching every filter given, newest first, fetching pages as needed."""
+        """Tasks matching every filter given, fetching pages as needed.
+
+        Newest first, unless `sort` and `order` say otherwise: `order` defaults
+        to "asc" (soonest first) for `sort="run_at"` and to "desc" for the rest.
+        List pending tasks by `run_at` to see them in the order they run.
+        """
         cursor: str | None = None
         while True:
             page = await self.list_page(
                 queue=queue,
                 state=state,
+                group_id=group_id,
                 idempotency_key=idempotency_key,
                 last_error=last_error,
                 created_after=created_after,
                 created_before=created_before,
+                sort=sort,
+                order=order,
                 cursor=cursor,
                 limit=page_size,
             )
@@ -300,10 +321,13 @@ class AsyncTasks:
         *,
         queue: str | None = None,
         state: TaskState | None = None,
+        group_id: str | None = None,
         idempotency_key: str | None = None,
         last_error: str | None = None,
         created_after: datetime | None = None,
         created_before: datetime | None = None,
+        sort: TaskSort | None = None,
+        order: SortOrder | None = None,
         cursor: str | None = None,
         limit: int | None = None,
     ) -> TaskPage:
@@ -311,10 +335,13 @@ class AsyncTasks:
         req = r.search_tasks(
             queue=queue,
             state=state,
+            group_id=group_id,
             idempotency_key=idempotency_key,
             last_error=last_error,
             created_after=created_after,
             created_before=created_before,
+            sort=sort,
+            order=order,
             cursor=cursor,
             limit=limit,
         )
@@ -328,6 +355,75 @@ class AsyncTasks:
         return Activity._from_json(await self._client._send(r.get_activity(range)))
 
 
+class AsyncGroups:
+    """Task groups: a set of tasks, and a callback task once all have finished.
+
+    Create a group, enqueue tasks with its `group_id`, then close it. Once it
+    is closed and every task has succeeded, failed or been cancelled, it
+    completes and enqueues its `on_complete` callback, once.
+    """
+
+    def __init__(self, client: AsyncWorkly) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        name: str | None = None,
+        idempotency_key: str | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
+    ) -> Group:
+        """Create an open group.
+
+        `on_complete` is the task to enqueue when the group completes, e.g.
+        `Callback(url="https://api.example.com/done")` or the same as a dict;
+        it is a POST of the group's summary as JSON. If `idempotency_key` matches an
+        existing group, that group is returned and nothing is created.
+        """
+        req = r.create_group(name, idempotency_key, on_complete)
+        return Group._from_json(await self._client._send(req))
+
+    async def get(self, group_id: str) -> Group:
+        return Group._from_json(await self._client._send(r.get_group(group_id)))
+
+    async def close(self, group_id: str) -> Group:
+        """Stop the group accepting tasks, so it completes once they have finished.
+
+        A group whose tasks have all finished completes at once. Closing a
+        closed group does nothing.
+        """
+        return Group._from_json(await self._client._send(r.close_group(group_id)))
+
+    async def list(
+        self,
+        *,
+        status: GroupStatus | None = None,
+        name: str | None = None,
+        page_size: int | None = None,
+    ) -> AsyncIterator[Group]:
+        """Groups, newest first, fetching pages as needed."""
+        cursor: str | None = None
+        while True:
+            page = await self.list_page(status=status, name=name, cursor=cursor, limit=page_size)
+            for group in page.groups:
+                yield group
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    async def list_page(
+        self,
+        *,
+        status: GroupStatus | None = None,
+        name: str | None = None,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> GroupPage:
+        """One page of `list`. Pass the previous page's `next_cursor` as `cursor`."""
+        req = r.list_groups(status=status, name=name, cursor=cursor, limit=limit)
+        return GroupPage._from_json(await self._client._send(req))
+
+
 class AsyncSchedules:
     """Cron schedules that call an endpoint. Separate from queues: each call is a run."""
 

{workly-0.1.0 → workly-0.2.1}/src/workly/_client.py

@@ -17,10 +17,14 @@ from ._models import (
     AlertChannelList,
     AlertChannelType,
     Attempt,
+    Callback,
     CronPreview,
     Delivery,
     EnqueueResult,
     FailureGroup,
+    Group,
+    GroupPage,
+    GroupStatus,
     HTTPMethod,
     MissedPolicy,
     OverlapPolicy,
@@ -30,8 +34,10 @@ from ._models import (
     RunPage,
     RunState,
     Schedule,
+    SortOrder,
     Task,
     TaskPage,
+    TaskSort,
     TaskState,
 )
 
@@ -60,6 +66,7 @@ class Workly:
         self._max_retries = max_retries
         self.queues = Queues(self)
         self.tasks = Tasks(self)
+        self.groups = Groups(self)
         self.schedules = Schedules(self)
         self.runs = Runs(self)
         self.alerts = Alerts(self)
@@ -208,6 +215,7 @@ class Tasks:
         idempotency_key: str | None = None,
         max_attempts: int | None = None,
         timeout_seconds: float | None = None,
+        group_id: str | None = None,
         traceparent: str | None = None,
     ) -> Task:
         """Enqueue a task to deliver to `url`.
@@ -215,7 +223,8 @@ class Tasks:
         `payload` is sent as JSON; `body` as raw text (use one). The queue is
         created with default settings if it doesn't exist. If
         `idempotency_key` matches a task already in the queue, that task is
-        returned and nothing is enqueued.
+        returned and nothing is enqueued. With `group_id`, the task joins
+        that group, which must be open.
         """
         spec = {
             "url": url,
@@ -229,6 +238,7 @@ class Tasks:
             "idempotency_key": idempotency_key,
             "max_attempts": max_attempts,
             "timeout_seconds": timeout_seconds,
+            "group_id": group_id,
         }
         return Task._from_json(self._client._send(r.enqueue(queue, spec, traceparent)))
 
@@ -270,22 +280,33 @@ class Tasks:
         *,
         queue: str | None = None,
         state: TaskState | None = None,
+        group_id: str | None = None,
         idempotency_key: str | None = None,
         last_error: str | None = None,
         created_after: datetime | None = None,
         created_before: datetime | None = None,
+        sort: TaskSort | None = None,
+        order: SortOrder | None = None,
         page_size: int | None = None,
     ) -> Iterator[Task]:
-        """Tasks matching every filter given, newest first, fetching pages as needed."""
+        """Tasks matching every filter given, fetching pages as needed.
+
+        Newest first, unless `sort` and `order` say otherwise: `order` defaults
+        to "asc" (soonest first) for `sort="run_at"` and to "desc" for the rest.
+        List pending tasks by `run_at` to see them in the order they run.
+        """
         cursor: str | None = None
         while True:
             page = self.list_page(
                 queue=queue,
                 state=state,
+                group_id=group_id,
                 idempotency_key=idempotency_key,
                 last_error=last_error,
                 created_after=created_after,
                 created_before=created_before,
+                sort=sort,
+                order=order,
                 cursor=cursor,
                 limit=page_size,
             )
@@ -299,10 +320,13 @@ class Tasks:
         *,
         queue: str | None = None,
         state: TaskState | None = None,
+        group_id: str | None = None,
         idempotency_key: str | None = None,
         last_error: str | None = None,
         created_after: datetime | None = None,
         created_before: datetime | None = None,
+        sort: TaskSort | None = None,
+        order: SortOrder | None = None,
         cursor: str | None = None,
         limit: int | None = None,
     ) -> TaskPage:
@@ -310,10 +334,13 @@ class Tasks:
         req = r.search_tasks(
             queue=queue,
             state=state,
+            group_id=group_id,
             idempotency_key=idempotency_key,
             last_error=last_error,
             created_after=created_after,
             created_before=created_before,
+            sort=sort,
+            order=order,
             cursor=cursor,
             limit=limit,
         )
@@ -327,6 +354,74 @@ class Tasks:
         return Activity._from_json(self._client._send(r.get_activity(range)))
 
 
+class Groups:
+    """Task groups: a set of tasks, and a callback task once all have finished.
+
+    Create a group, enqueue tasks with its `group_id`, then close it. Once it
+    is closed and every task has succeeded, failed or been cancelled, it
+    completes and enqueues its `on_complete` callback, once.
+    """
+
+    def __init__(self, client: Workly) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        name: str | None = None,
+        idempotency_key: str | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
+    ) -> Group:
+        """Create an open group.
+
+        `on_complete` is the task to enqueue when the group completes, e.g.
+        `Callback(url="https://api.example.com/done")` or the same as a dict;
+        it is a POST of the group's summary as JSON. If `idempotency_key` matches an
+        existing group, that group is returned and nothing is created.
+        """
+        req = r.create_group(name, idempotency_key, on_complete)
+        return Group._from_json(self._client._send(req))
+
+    def get(self, group_id: str) -> Group:
+        return Group._from_json(self._client._send(r.get_group(group_id)))
+
+    def close(self, group_id: str) -> Group:
+        """Stop the group accepting tasks, so it completes once they have finished.
+
+        A group whose tasks have all finished completes at once. Closing a
+        closed group does nothing.
+        """
+        return Group._from_json(self._client._send(r.close_group(group_id)))
+
+    def list(
+        self,
+        *,
+        status: GroupStatus | None = None,
+        name: str | None = None,
+        page_size: int | None = None,
+    ) -> Iterator[Group]:
+        """Groups, newest first, fetching pages as needed."""
+        cursor: str | None = None
+        while True:
+            page = self.list_page(status=status, name=name, cursor=cursor, limit=page_size)
+            yield from page.groups
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    def list_page(
+        self,
+        *,
+        status: GroupStatus | None = None,
+        name: str | None = None,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> GroupPage:
+        """One page of `list`. Pass the previous page's `next_cursor` as `cursor`."""
+        req = r.list_groups(status=status, name=name, cursor=cursor, limit=limit)
+        return GroupPage._from_json(self._client._send(req))
+
+
 class Schedules:
     """Cron schedules that call an endpoint. Separate from queues: each call is a run."""
 

{workly-0.1.0 → workly-0.2.1}/src/workly/_models.py

@@ -5,11 +5,15 @@ Unknown fields are ignored, so newer servers don't break older SDKs.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from collections.abc import Mapping
+from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Literal
 
 TaskState = Literal["pending", "running", "succeeded", "failed", "cancelled"]
+TaskSort = Literal["created_at", "run_at", "last_attempt_at", "attempt_count"]
+"""What tasks are listed by. `run_at` is when a task runs next: pending tasks run in that order."""
+SortOrder = Literal["asc", "desc"]
 HTTPMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
 AttemptOutcome = Literal["success", "http_error", "timeout", "network_error", "lost"]
 RunState = Literal["pending", "running", "succeeded", "failed", "cancelled", "skipped"]
@@ -17,6 +21,8 @@ RunTrigger = Literal["schedule", "manual"]
 SkipReason = Literal["overlap", "missed"]
 OverlapPolicy = Literal["skip", "allow"]
 MissedPolicy = Literal["skip", "catch_up"]
+GroupStatus = Literal["open", "running", "succeeded", "failed"]
+"""`open` accepts tasks; `running` is closed with tasks unfinished; the other two are final."""
 
 
 def _time(value: str) -> datetime:
@@ -218,6 +224,8 @@ class Task:
     """When the latest attempt finished."""
     retried_at: datetime | None
     """When the task was last retried by hand."""
+    group_id: str | None = None
+    """The group the task belongs to, if any."""
 
     @classmethod
     def _from_json(cls, d: dict[str, Any]) -> Task:
@@ -243,6 +251,7 @@ class Task:
             finished_at=_opt_time(d.get("finished_at")),
             last_attempt_at=_opt_time(d.get("last_attempt_at")),
             retried_at=_opt_time(d.get("retried_at")),
+            group_id=d.get("group_id"),
         )
 
 
@@ -500,3 +509,89 @@ class AlertChannelList:
             channels=[AlertChannel._from_json(c) for c in d["channels"]],
             email_enabled=d["email_enabled"],
         )
+
+
+CALLBACK_QUEUE = "_callbacks"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Callback:
+    """A task Workly enqueues when something completes: a POST to `url` saying what completed.
+
+    A group's callback has the group's summary as its JSON body. It is
+    delivered like any task in its queue, with that queue's retries.
+    """
+
+    url: str
+    queue: str = CALLBACK_QUEUE
+    """The queue to enqueue the callback into. `_callbacks`, the default, is
+    created by Workly; configure it like any queue to change its retries."""
+    headers: Mapping[str, str] = field(default_factory=dict[str, str])
+    """Headers sent with the callback. `Workly-*` headers are reserved."""
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> Callback:
+        return cls(
+            url=d["url"], queue=d.get("queue") or CALLBACK_QUEUE, headers=d.get("headers") or {}
+        )
+
+
+GroupCallback = Callback
+"""Deprecated: use `Callback`."""
+
+
+@dataclass(frozen=True, slots=True)
+class Group:
+    """A set of tasks tracked together, with a callback once all have finished."""
+
+    id: str
+    name: str | None
+    status: GroupStatus
+    idempotency_key: str | None
+    total: int
+    succeeded: int
+    failed: int
+    cancelled: int
+    remaining: int
+    """Tasks still pending or running."""
+    on_complete: Callback | None
+    callback_task_id: str | None
+    """The callback task, once the group has completed."""
+    created_at: datetime
+    closed_at: datetime | None
+    finished_at: datetime | None
+    """When the group completed."""
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> Group:
+        cb = d.get("on_complete")
+        return cls(
+            id=d["id"],
+            name=d.get("name"),
+            status=d["status"],
+            idempotency_key=d.get("idempotency_key"),
+            total=d["total"],
+            succeeded=d["succeeded"],
+            failed=d["failed"],
+            cancelled=d["cancelled"],
+            remaining=d["remaining"],
+            on_complete=None if cb is None else Callback._from_json(cb),
+            callback_task_id=d.get("callback_task_id"),
+            created_at=_time(d["created_at"]),
+            closed_at=_opt_time(d.get("closed_at")),
+            finished_at=_opt_time(d.get("finished_at")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class GroupPage:
+    groups: list[Group]
+    next_cursor: str | None
+    """Pass as `cursor` to get the next page. None on the last page."""
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> GroupPage:
+        return cls(
+            groups=[Group._from_json(g) for g in d["groups"]],
+            next_cursor=d.get("next_cursor"),
+        )

{workly-0.1.0 → workly-0.2.1}/src/workly/_requests.py

@@ -14,7 +14,17 @@ from importlib.metadata import PackageNotFoundError, version
 from typing import Any, Required, TypedDict
 from urllib.parse import quote
 
-from ._models import AlertChannelType, HTTPMethod, RunState, TaskState
+from ._models import (
+    CALLBACK_QUEUE,
+    AlertChannelType,
+    Callback,
+    GroupStatus,
+    HTTPMethod,
+    RunState,
+    SortOrder,
+    TaskSort,
+    TaskState,
+)
 
 DEFAULT_URL = "http://localhost:7337"
 
@@ -64,6 +74,32 @@ class TaskSpec(TypedDict, total=False):
     idempotency_key: str
     max_attempts: int
     timeout_seconds: float
+    group_id: str
+
+
+class CallbackDict(TypedDict, total=False):
+    """A `Callback` as a dict, with the same fields."""
+
+    url: Required[str]
+    queue: str
+    headers: Mapping[str, str]
+
+
+GroupCallbackSpec = CallbackDict
+"""Deprecated: use `Callback` or `CallbackDict`."""
+
+
+def callback_body(cb: Callback | CallbackDict) -> dict[str, Any]:
+    if isinstance(cb, Callback):
+        url, queue, headers = cb.url, cb.queue, cb.headers
+    else:
+        url, queue, headers = cb["url"], cb.get("queue", CALLBACK_QUEUE), cb.get("headers", {})
+    body: dict[str, Any] = {"url": url}
+    if queue != CALLBACK_QUEUE:
+        body["queue"] = queue
+    if headers:
+        body["headers"] = dict(headers)
+    return body
 
 
 def task_body(spec: Mapping[str, Any]) -> dict[str, Any]:
@@ -178,10 +214,13 @@ def search_tasks(
     *,
     queue: str | None,
     state: TaskState | None,
+    group_id: str | None,
     idempotency_key: str | None,
     last_error: str | None,
     created_after: datetime | None,
     created_before: datetime | None,
+    sort: TaskSort | None,
+    order: SortOrder | None,
     cursor: str | None,
     limit: int | None,
 ) -> Request:
@@ -190,6 +229,8 @@ def search_tasks(
         params["queue"] = queue
     if state is not None:
         params["state"] = state
+    if group_id is not None:
+        params["group_id"] = group_id
     if idempotency_key is not None:
         params["idempotency_key"] = idempotency_key
     if last_error is not None:
@@ -198,6 +239,10 @@ def search_tasks(
         params["created_after"] = _timestamp(created_after, "created_after")
     if created_before is not None:
         params["created_before"] = _timestamp(created_before, "created_before")
+    if sort is not None:
+        params["sort"] = sort
+    if order is not None:
+        params["order"] = order
     if cursor is not None:
         params["cursor"] = cursor
     if limit is not None:
@@ -226,6 +271,45 @@ def retry_task(task_id: str) -> Request:
     return Request("POST", f"/v1/tasks/{_q(task_id)}/retry")
 
 
+# Groups
+
+
+def create_group(
+    name: str | None, idempotency_key: str | None, on_complete: Callback | CallbackDict | None
+) -> Request:
+    body: dict[str, Any] = {}
+    if name is not None:
+        body["name"] = name
+    if idempotency_key is not None:
+        body["idempotency_key"] = idempotency_key
+    if on_complete is not None:
+        body["on_complete"] = callback_body(on_complete)
+    return Request("POST", "/v1/groups", json=body, idempotent=idempotency_key is not None)
+
+
+def get_group(group_id: str) -> Request:
+    return Request("GET", f"/v1/groups/{_q(group_id)}", idempotent=True)
+
+
+def list_groups(
+    *, status: GroupStatus | None, name: str | None, cursor: str | None, limit: int | None
+) -> Request:
+    params: dict[str, str] = {}
+    if status is not None:
+        params["status"] = status
+    if name is not None:
+        params["name"] = name
+    if cursor is not None:
+        params["cursor"] = cursor
+    if limit is not None:
+        params["limit"] = str(limit)
+    return Request("GET", "/v1/groups", params=params, idempotent=True)
+
+
+def close_group(group_id: str) -> Request:
+    return Request("POST", f"/v1/groups/{_q(group_id)}/close", idempotent=True)
+
+
 # Schedules and runs