dex-connector-hackernews 0.1.0__tar.gz

dex_connector_hackernews-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+/.dex-local/dexcli
+/.dex-local/dex-server-zd
+/.dex-local/data/
+/.dex-local/cli.log
+/.dex-local/visualize.json
+/.dex-local/visualize.err

dex_connector_hackernews-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: dex-connector-hackernews
+Version: 0.1.0
+Summary: Hacker News connector for Dex Flows
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: dex-connectors-sdk==0.1.0
+Requires-Dist: dex-python-sdk>=1.28.0
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Hacker News connector for Python
+
+Install with `pip install dex-connector-hackernews==0.1.0`. The package
+requires `dex-connectors-sdk==0.1.0` and `dex-python-sdk>=1.28.0`, and
+implements the manifest Queries `listStoryIDs` and `getItem` with the same
+branches, defaults, and failure classification as the Go module. The public
+API needs no credentials.
+
+## Operations
+
+| Operation | Factory | Happy branch | Optional branches |
+| --- | --- | --- | --- |
+| `listStoryIDs` | `new_list_story_ids_step` | `listed` | `providerRejected`, `invalidResponse`, `defect` |
+| `getItem` | `new_get_item_step` | `found` | `notFound`, `providerRejected`, `invalidResponse`, `defect` |
+
+`listStoryIDs` reads the `top` (default), `best`, `new`, `ask`, or `show` feed
+and keeps the first `limit` IDs (default 50, at most 500), reporting whether
+more remained. `getItem` returns a public story, comment, job, poll, or poll
+option with its discussion URL; a missing, deleted, or dead item selects
+`notFound`. 408, 429, 5xx, and transport failures retry; other non-200
+responses select `providerRejected`. Item `text_html` is untrusted provider
+HTML.
+
+## Example
+
+[`examples/top_story`](examples/top_story/flow.py) reads a feed's first story ID
+and then that story. Run the Worker with
+`uv run python -m examples.top_story.worker` after `dexcli dev` has loaded a
+project containing the `hackernews` connection. It is smaller than the Go
+daily-digest example, which also summarizes stories with an LLM.
+
+## Tests
+
+`hackernewsmock.Mock` scripts both Queries and defaults to the manifest
+answers. Run `uv run pytest tests` for provider parity and manifest contract
+checks.

dex_connector_hackernews-0.1.0/README.md

@@ -0,0 +1,36 @@
+# Hacker News connector for Python
+
+Install with `pip install dex-connector-hackernews==0.1.0`. The package
+requires `dex-connectors-sdk==0.1.0` and `dex-python-sdk>=1.28.0`, and
+implements the manifest Queries `listStoryIDs` and `getItem` with the same
+branches, defaults, and failure classification as the Go module. The public
+API needs no credentials.
+
+## Operations
+
+| Operation | Factory | Happy branch | Optional branches |
+| --- | --- | --- | --- |
+| `listStoryIDs` | `new_list_story_ids_step` | `listed` | `providerRejected`, `invalidResponse`, `defect` |
+| `getItem` | `new_get_item_step` | `found` | `notFound`, `providerRejected`, `invalidResponse`, `defect` |
+
+`listStoryIDs` reads the `top` (default), `best`, `new`, `ask`, or `show` feed
+and keeps the first `limit` IDs (default 50, at most 500), reporting whether
+more remained. `getItem` returns a public story, comment, job, poll, or poll
+option with its discussion URL; a missing, deleted, or dead item selects
+`notFound`. 408, 429, 5xx, and transport failures retry; other non-200
+responses select `providerRejected`. Item `text_html` is untrusted provider
+HTML.
+
+## Example
+
+[`examples/top_story`](examples/top_story/flow.py) reads a feed's first story ID
+and then that story. Run the Worker with
+`uv run python -m examples.top_story.worker` after `dexcli dev` has loaded a
+project containing the `hackernews` connection. It is smaller than the Go
+daily-digest example, which also summarizes stories with an LLM.
+
+## Tests
+
+`hackernewsmock.Mock` scripts both Queries and defaults to the manifest
+answers. Run `uv run pytest tests` for provider parity and manifest contract
+checks.

dex_connector_hackernews-0.1.0/examples/top_story/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Hacker News top story example Flow."""

dex_connector_hackernews-0.1.0/examples/top_story/flow.py

@@ -0,0 +1,133 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Runnable Hacker News Flow: read a feed's first story ID, then that story."""
+
+from dataclasses import dataclass, field
+
+import dex
+from dex_connectors.sdk import QueryResult
+
+from dex_connectors.hackernews import (
+    Connection,
+    GetItemInput,
+    Item,
+    ListStoryIDsInput,
+    StoryIDs,
+    new_get_item_step,
+    new_list_story_ids_step,
+)
+
+FLOW_TYPE = "HackerNewsTopStory"
+CONNECTION_NAME = "hackernews"
+_LIST_STEP_TYPE = "ListFeedStoryIDs"
+_GET_STEP_TYPE = "ReadTopStory"
+_ANNOTATION_GROUP = {"groupId": "hacker-news", "groupLabel": "Hacker News"}
+
+
+@dataclass(frozen=True, slots=True)
+class TopStoryRequest:
+    """Feed to read: top, best, new, ask, or show; blank means top."""
+
+    feed: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class TopStoryOutcome:
+    """The feed's first story, or an empty item when the feed was empty."""
+
+    story: Item = field(default_factory=Item)
+
+
+_OUTCOME = dex.Attribute("hackernews-top-story-outcome", TopStoryOutcome)
+
+
+def map_to_list_story_ids_input(request: TopStoryRequest) -> ListStoryIDsInput:
+    """Read only the first ID of the requested feed."""
+    return ListStoryIDsInput(feed=request.feed, limit=1)
+
+
+def map_to_get_item_input(item: GetItemInput) -> GetItemInput:
+    """Read the story chosen from the feed unchanged."""
+    return item
+
+
+# dex:group group-id:top-story group-label:"Top story"
+# dex:explanation text:"Start the lookup with the requested feed."
+class _StartRequest(dex.Step[TopStoryRequest]):
+    def get_step_type(self) -> str:
+        return "StartTopStory"
+
+    def execute(self, context: dex.Context, input: TopStoryRequest) -> dex.StepDecision:
+        return dex.go_to(dex.StepRef(_LIST_STEP_TYPE), input)
+
+
+# dex:group group-id:top-story group-label:"Top story"
+# dex:explanation text:"Complete when the feed is empty, otherwise read its first story."
+class _AfterFeed(dex.Step[QueryResult[StoryIDs]]):
+    def get_step_type(self) -> str:
+        return "AfterFeedSnapshot"
+
+    def execute(self, context: dex.Context, input: QueryResult[StoryIDs]) -> dex.StepDecision:
+        if not input.value.ids:
+            outcome = TopStoryOutcome()
+            _OUTCOME.set(context, outcome)
+            return dex.graceful_complete(outcome)
+        return dex.go_to(dex.StepRef(_GET_STEP_TYPE), GetItemInput(input.value.ids[0]))
+
+
+# dex:group group-id:top-story group-label:"Top story"
+# dex:explanation text:"Record the story and complete the Flow."
+class _CompleteStory(dex.Step[QueryResult[Item]]):
+    def get_step_type(self) -> str:
+        return "CompleteTopStory"
+
+    def execute(self, context: dex.Context, input: QueryResult[Item]) -> dex.StepDecision:
+        outcome = TopStoryOutcome(input.value)
+        _OUTCOME.set(context, outcome)
+        return dex.graceful_complete(outcome)
+
+
+class TopStoryFlow(dex.Flow[TopStoryRequest]):
+    """Read a feed's first story through the static hackernews connection."""
+
+    def __init__(self, connection: Connection) -> None:
+        if connection.reference.name != CONNECTION_NAME:
+            raise ValueError("top story requires the static hackernews connection")
+        self._start = _StartRequest()
+        self._after_feed = _AfterFeed()
+        self._complete = _CompleteStory()
+        self._list = new_list_story_ids_step(
+            step_type=_LIST_STEP_TYPE,
+            step_input_type=TopStoryRequest,
+            annotations={
+                **_ANNOTATION_GROUP,
+                "explanation": "Read the first story ID of the requested feed.",
+            },
+            connection=connection,
+            connection_name=CONNECTION_NAME,
+            map_to_operation_input=map_to_list_story_ids_input,
+            listed=self._after_feed,
+        )
+        self._get = new_get_item_step(
+            step_type=_GET_STEP_TYPE,
+            step_input_type=GetItemInput,
+            annotations={**_ANNOTATION_GROUP, "explanation": "Read the story and its discussion link."},
+            connection=connection,
+            connection_name=CONNECTION_NAME,
+            map_to_operation_input=map_to_get_item_input,
+            found=self._complete,
+        )
+
+    def get_flow_type(self) -> str:
+        """Return the stable Flow identity used in Dex Web."""
+        return FLOW_TYPE
+
+    def get_steps(self) -> dex.StepList[TopStoryRequest]:
+        """Register the start, both Hacker News reads, and their result Steps."""
+        return dex.StepList.start_step(self._start).other_steps(
+            self._list, self._after_feed, self._get, self._complete
+        )
+
+    def get_persistence_schema(self) -> dex.PersistenceSchema:
+        """Persist the story outcome."""
+        return dex.PersistenceSchema.of(_OUTCOME)

dex_connector_hackernews-0.1.0/examples/top_story/worker.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Worker entrypoint for the Hacker News top story Flow."""
+
+import asyncio
+import os
+import tempfile
+from pathlib import Path
+
+import dex
+from dex_connectors.sdk.projectconfig import load_from_environment
+
+from dex_connectors.hackernews import new_project_connection
+
+from .flow import CONNECTION_NAME, TopStoryFlow
+
+
+async def run_worker() -> None:
+    """Load the named Dex Web connection and serve top story lookups."""
+    project = await load_from_environment()
+    connection = None
+    cache = None
+    try:
+        connection = new_project_connection(project, CONNECTION_NAME)
+        registry = dex.Registry([TopStoryFlow(connection)], allow_async_handlers=True)
+        cache_directory = os.environ.get(
+            "DEX_BLOB_CACHE_DIR", str(Path(tempfile.gettempdir()) / "dex-hackernews-top-story-blobs")
+        )
+        cache = dex.open_blob_cache(dex.BlobCacheConfig(cache_directory, 1 << 30))
+        worker = dex.AsyncWorker(
+            registry,
+            cache,
+            dex.WorkerOptions(server_address=os.environ.get("DEX_FLOW_SERVICE_ADDRESS", "localhost:8801")),
+        )
+        async with worker:
+            await worker.start()
+    finally:
+        if connection is not None:
+            await connection.aclose()
+        if cache is not None:
+            cache.close()
+        await project.close()
+
+
+def main() -> None:
+    """Run until the Worker stops or the process receives an interrupt."""
+    asyncio.run(run_worker())
+
+
+if __name__ == "__main__":
+    main()

dex_connector_hackernews-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dex-connector-hackernews"
+version = "0.1.0"
+description = "Hacker News connector for Dex Flows"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["dex-connectors-sdk==0.1.0", "dex-python-sdk>=1.28.0", "httpx>=0.27"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.13", "ruff>=0.7", "pyyaml>=6", "types-PyYAML>=6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dex_connectors"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+explicit_package_bases = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

dex_connector_hackernews-0.1.0/src/dex_connectors/hackernews/__init__.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Hacker News feed and item Queries for Dex connector Steps."""
+
+from .client import (
+    CONNECTOR_ID,
+    DEFECT,
+    FEEDS,
+    FOUND,
+    GET_ITEM_DEFINITION,
+    INVALID_RESPONSE,
+    LIST_STORY_IDS_DEFINITION,
+    LISTED,
+    NOT_FOUND,
+    PROVIDER_REJECTED,
+    Client,
+    Config,
+    GetItemOperation,
+    ListStoryIDsOperation,
+)
+from .connection import Connection, new_connection, new_connection_with_operations, new_project_connection
+from .models import GetItemInput, Item, ListStoryIDsInput, StoryIDs
+from .steps import new_get_item_step, new_list_story_ids_step
+
+__all__ = [
+    "Client",
+    "Config",
+    "Connection",
+    "GetItemInput",
+    "GetItemOperation",
+    "Item",
+    "ListStoryIDsInput",
+    "ListStoryIDsOperation",
+    "StoryIDs",
+    "new_connection",
+    "new_connection_with_operations",
+    "new_get_item_step",
+    "new_list_story_ids_step",
+    "new_project_connection",
+    "CONNECTOR_ID",
+    "DEFECT",
+    "FEEDS",
+    "FOUND",
+    "GET_ITEM_DEFINITION",
+    "INVALID_RESPONSE",
+    "LIST_STORY_IDS_DEFINITION",
+    "LISTED",
+    "NOT_FOUND",
+    "PROVIDER_REJECTED",
+]

dex_connector_hackernews-0.1.0/src/dex_connectors/hackernews/_generated/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT

dex_connector_hackernews-0.1.0/src/dex_connectors/hackernews/_generated/config.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# ruff: noqa
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+
+    base_url: str = "https://hacker-news.firebaseio.com/v0"
+    timeout_seconds: float = 15
+    max_response_bytes: int = 1048576
+
+setattr(Config, '__module__', 'dex_connectors.hackernews.client')

dex_connector_hackernews-0.1.0/src/dex_connectors/hackernews/_generated/definitions.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# ruff: noqa
+
+from datetime import timedelta
+
+from dex_connectors.sdk import (
+    BranchDefinition,
+    MutationDefinition,
+    OperationRef,
+    QueryDefinition,
+    RetryPolicy,
+    StepDefaults,
+    default_connector_step_execute_retry_policy,
+)
+
+CONNECTOR_ID = "hacker-news-daily"
+PROVIDER = "hacker-news"
+LIST_STORY_IDS_OPERATION_ID = "listStoryIDs"
+GET_ITEM_OPERATION_ID = "getItem"
+DEFECT = "defect"
+FOUND = "found"
+INVALID_RESPONSE = "invalidResponse"
+LISTED = "listed"
+NOT_FOUND = "notFound"
+PROVIDER_REJECTED = "providerRejected"
+
+LIST_STORY_IDS_DEFINITION = QueryDefinition(
+    OperationRef(CONNECTOR_ID, LIST_STORY_IDS_OPERATION_ID),
+    (
+        BranchDefinition(LISTED, "The feed snapshot was read.", False),
+        BranchDefinition(PROVIDER_REJECTED, "Hacker News rejected the request.", True),
+        BranchDefinition(INVALID_RESPONSE, "Hacker News returned malformed or oversized data.", True),
+        BranchDefinition(DEFECT, "Local input or connection configuration is invalid.", True),
+    ),
+    StepDefaults(
+        timedelta(seconds=30),
+        2,
+        execute_retry=RetryPolicy(timedelta(seconds=1), 2, timedelta(seconds=30), 0, timedelta(seconds=3900)),
+    ),
+)
+
+GET_ITEM_DEFINITION = QueryDefinition(
+    OperationRef(CONNECTOR_ID, GET_ITEM_OPERATION_ID),
+    (
+        BranchDefinition(FOUND, "The public item was read.", False),
+        BranchDefinition(NOT_FOUND, "The item is missing, deleted, or dead.", True),
+        BranchDefinition(PROVIDER_REJECTED, "Hacker News rejected the request.", True),
+        BranchDefinition(INVALID_RESPONSE, "Hacker News returned malformed or oversized data.", True),
+        BranchDefinition(DEFECT, "Local input or connection configuration is invalid.", True),
+    ),
+    StepDefaults(
+        timedelta(seconds=30),
+        2,
+        execute_retry=RetryPolicy(timedelta(seconds=1), 2, timedelta(seconds=30), 0, timedelta(seconds=3900)),
+    ),
+)

dex_connector_hackernews-0.1.0/src/dex_connectors/hackernews/_generated/models.py

@@ -0,0 +1,98 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# ruff: noqa
+
+from dataclasses import dataclass, field as _dataclass_field
+from datetime import UTC, datetime
+from typing import Any
+
+from .timestamps import parse_go_datetime, validate_go_datetime
+
+def _replace_nil_slices(value: Any, depth: int) -> Any:
+    if value is None:
+        return ()
+    if depth == 1:
+        return tuple(value)
+    return tuple(_replace_nil_slices(item, depth - 1) for item in value)
+
+
+# ListStoryIDsInput selects one feed snapshot. It does not select a historical time window.
+@dataclass(frozen=True, slots=True)
+class ListStoryIDsInput:
+    # Feed is top, best, new, ask, or show. Empty selects top.
+    feed: str = ''
+    # Limit bounds returned IDs from 1 through 500. Zero selects 50.
+    limit: int = 0
+
+
+setattr(ListStoryIDsInput, '__module__', 'dex_connectors.hackernews.models')
+
+
+# StoryIDs contains the start of a feed in the provider's current display order.
+@dataclass(frozen=True, slots=True)
+class StoryIDs:
+    # IDs contains at most the requested limit. Top stories can include jobs.
+    ids: tuple[int, ...] = ()
+    # HasMore reports that the API returned more IDs than this operation retained. The API has no page cursor.
+    has_more: bool = _dataclass_field(default=False, metadata={'dex_json_name': 'hasMore'})
+    # ObservedAt is the UTC time when this response was read.
+    observed_at: datetime = _dataclass_field(default_factory=lambda: datetime.min.replace(tzinfo=UTC), metadata={'dex_json_name': 'observedAt', 'dex_json_format': 'rfc3339'})
+
+    def __post_init__(self) -> None:
+        if isinstance(self.observed_at, str):
+            object.__setattr__(self, 'observed_at', parse_go_datetime(self.observed_at, 'observed_at'))
+        elif self.observed_at is not None:
+            validate_go_datetime(self.observed_at, 'observed_at')
+        object.__setattr__(self, 'ids', _replace_nil_slices(self.ids, 1))
+
+
+StoryIDs.__annotations__['ids'] = tuple[int, ...] | None
+StoryIDs.__dataclass_fields__['ids'].type = tuple[int, ...] | None
+setattr(StoryIDs, '__module__', 'dex_connectors.hackernews.models')
+
+
+# GetItemInput identifies one story, comment, job, poll, or poll option.
+@dataclass(frozen=True, slots=True)
+class GetItemInput:
+    # ID is a positive Hacker News item ID.
+    id: int = 0
+
+
+setattr(GetItemInput, '__module__', 'dex_connectors.hackernews.models')
+
+
+# Item preserves public API fields and adds the exact Hacker News permalink.
+# TextHTML and Title are untrusted provider text. Applications must escape or sanitize them before HTML rendering.
+@dataclass(frozen=True, slots=True)
+class Item:
+    # ID identifies this item.
+    id: int = 0
+    # Type is story, comment, job, poll, or pollopt.
+    type: str = ''
+    # By is the author's public username, when available.
+    by: str = _dataclass_field(default='', metadata={'dex_json_omit_default': True})
+    # Time is the creation time in Unix seconds, when available.
+    time: int = _dataclass_field(default=0, metadata={'dex_json_omit_default': True})
+    # Title is the provider's title, which can contain HTML entities.
+    title: str = _dataclass_field(default='', metadata={'dex_json_omit_default': True})
+    # TextHTML is the submitted story or comment body. Linked article content is not included.
+    text: str = _dataclass_field(default='', metadata={'dex_json_omit_default': True})
+    # URL is the submitted external URL. Ask HN and other text posts may have no URL.
+    url: str = _dataclass_field(default='', metadata={'dex_json_omit_default': True})
+    # DiscussionURL links directly to this story or comment on Hacker News.
+    discussion_url: str = _dataclass_field(default='', metadata={'dex_json_name': 'discussionUrl'})
+    # Score is the story score. Hacker News does not expose comment scores.
+    score: int = _dataclass_field(default=0, metadata={'dex_json_omit_default': True})
+    # Descendants is the provider's comment count for a story or poll.
+    descendants: int = _dataclass_field(default=0, metadata={'dex_json_omit_default': True})
+    # Parent identifies a comment's parent item or a poll option's poll.
+    parent: int = _dataclass_field(default=0, metadata={'dex_json_omit_default': True})
+    # Kids contains child IDs in the provider's ranked display order.
+    kids: tuple[int, ...] = _dataclass_field(default=(), metadata={'dex_json_omit_default': True})
+    # Deleted reports a deleted item. GetItem selects notFound instead of returning a tombstone.
+    deleted: bool = _dataclass_field(default=False, metadata={'dex_json_omit_default': True})
+    # Dead reports a moderated item. GetItem selects notFound instead of returning it.
+    dead: bool = _dataclass_field(default=False, metadata={'dex_json_omit_default': True})
+
+
+setattr(Item, '__module__', 'dex_connectors.hackernews.models')

dex_connector_hackernews-0.1.0/src/dex_connectors/hackernews/_generated/steps.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# ruff: noqa
+
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar
+
+import dex
+from dex_connectors.sdk import (
+    QueryResult,
+    QueryStep,
+    QueryStepConfig,
+    StepAnnotations,
+)
+
+from ..connection import Connection
+from ..models import GetItemInput, Item, ListStoryIDsInput, StoryIDs
+
+StepInput = TypeVar("StepInput")
+
+def new_list_story_ids_step(
+    *,
+    step_type: str,
+    step_input_type: type[StepInput],
+    annotations: StepAnnotations | Mapping[str, str],
+    connection: Connection,
+    connection_name: str,
+    map_to_operation_input: Callable[[StepInput], ListStoryIDsInput],
+    listed: dex.StepTarget[QueryResult[StoryIDs]],
+    provider_rejected: dex.StepTarget[QueryResult[StoryIDs]] | None = None,
+    invalid_response: dex.StepTarget[QueryResult[StoryIDs]] | None = None,
+    defect: dex.StepTarget[QueryResult[StoryIDs]] | None = None,
+    result_attribute: dex.Attribute[QueryResult[StoryIDs]] | None = None,
+    step_options_override: dex.StepOptions | None = None,
+) -> QueryStep[StepInput, ListStoryIDsInput, StoryIDs]:
+    if connection is None or connection.reference.name != connection_name:
+        raise ValueError("Hacker News Daily Step connection name must match its connection reference")
+    if isinstance(annotations, StepAnnotations):
+        step_annotations = annotations
+    else:
+        if not isinstance(annotations, Mapping) or set(annotations) != {"groupId", "groupLabel", "explanation"}:
+            raise ValueError("Hacker News Daily Step annotations require groupId, groupLabel, and explanation")
+        if any(not isinstance(value, str) for value in annotations.values()):
+            raise ValueError("Hacker News Daily Step annotations must be strings")
+        step_annotations = StepAnnotations(annotations["groupId"], annotations["groupLabel"], annotations["explanation"])
+    branches = {
+        "listed": listed,
+    }
+    if provider_rejected is not None:
+        branches["providerRejected"] = provider_rejected
+    if invalid_response is not None:
+        branches["invalidResponse"] = invalid_response
+    if defect is not None:
+        branches["defect"] = defect
+    return QueryStep(
+        QueryStepConfig(
+            step_type=step_type,
+            step_input_type=step_input_type,
+            annotations=step_annotations,
+            operation=_bound_operation(connection, "list_story_ids"),
+            connection=connection.reference,
+            map_to_operation_input=map_to_operation_input,
+            branches=branches,
+            result_attribute=result_attribute,
+            step_options_override=step_options_override,
+        )
+    )
+
+setattr(new_list_story_ids_step, '__module__', 'dex_connectors.hackernews.steps')
+
+def new_get_item_step(
+    *,
+    step_type: str,
+    step_input_type: type[StepInput],
+    annotations: StepAnnotations | Mapping[str, str],
+    connection: Connection,
+    connection_name: str,
+    map_to_operation_input: Callable[[StepInput], GetItemInput],
+    found: dex.StepTarget[QueryResult[Item]],
+    not_found: dex.StepTarget[QueryResult[Item]] | None = None,
+    provider_rejected: dex.StepTarget[QueryResult[Item]] | None = None,
+    invalid_response: dex.StepTarget[QueryResult[Item]] | None = None,
+    defect: dex.StepTarget[QueryResult[Item]] | None = None,
+    result_attribute: dex.Attribute[QueryResult[Item]] | None = None,
+    step_options_override: dex.StepOptions | None = None,
+) -> QueryStep[StepInput, GetItemInput, Item]:
+    if connection is None or connection.reference.name != connection_name:
+        raise ValueError("Hacker News Daily Step connection name must match its connection reference")
+    if isinstance(annotations, StepAnnotations):
+        step_annotations = annotations
+    else:
+        if not isinstance(annotations, Mapping) or set(annotations) != {"groupId", "groupLabel", "explanation"}:
+            raise ValueError("Hacker News Daily Step annotations require groupId, groupLabel, and explanation")
+        if any(not isinstance(value, str) for value in annotations.values()):
+            raise ValueError("Hacker News Daily Step annotations must be strings")
+        step_annotations = StepAnnotations(annotations["groupId"], annotations["groupLabel"], annotations["explanation"])
+    branches = {
+        "found": found,
+    }
+    if not_found is not None:
+        branches["notFound"] = not_found
+    if provider_rejected is not None:
+        branches["providerRejected"] = provider_rejected
+    if invalid_response is not None:
+        branches["invalidResponse"] = invalid_response
+    if defect is not None:
+        branches["defect"] = defect
+    return QueryStep(
+        QueryStepConfig(
+            step_type=step_type,
+            step_input_type=step_input_type,
+            annotations=step_annotations,
+            operation=_bound_operation(connection, "get_item"),
+            connection=connection.reference,
+            map_to_operation_input=map_to_operation_input,
+            branches=branches,
+            result_attribute=result_attribute,
+            step_options_override=step_options_override,
+        )
+    )
+
+setattr(new_get_item_step, '__module__', 'dex_connectors.hackernews.steps')
+
+
+def _bound_operation(connection: Connection, operation_name: str) -> Any:
+    source = getattr(connection, operation_name, None)
+    if source is None:
+        source = getattr(getattr(connection, "operations", None), operation_name, None)
+    if source is None:
+        raise ValueError(f"connection operation {operation_name} is missing")
+    return source() if callable(source) else source