dex-connector-hackernews 0.1.0__py3-none-any.whl

dex_connector_hackernews-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+dex_connectors/hackernews/__init__.py,sha256=CRXdSt7bbr1RfQKh1ihjpHnrowbCt78gGh87hStj1oU,1179
+dex_connectors/hackernews/client.py,sha256=PezLx_mJfVL2iW2-rJtYaoCXv0XisV6v_JKJ59MVIhY,13258
+dex_connectors/hackernews/connection.py,sha256=55E2yFmIuIZ3_4bMUEVHNXvPmnk0BBhJV8Z03qugOYk,4635
+dex_connectors/hackernews/dex-connector.json,sha256=zqC5F0EDhuYlmxyQzkj1E9fEKGjA8XZBFqz0WKTFSWM,1883
+dex_connectors/hackernews/models.py,sha256=ofY_XYYae3HXIEUTerRilVhKQjZqRdN0TVsP1g-pPDY,1804
+dex_connectors/hackernews/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dex_connectors/hackernews/steps.py,sha256=YGSs3XTl1MaCpZmAwiiHjSCC3u77GcgbHvSCJunyvng,1256
+dex_connectors/hackernews/_generated/__init__.py,sha256=ShfMsAGzSt4xuhCaf20ibgtfXl4pXomZb00ovUw6CeI,66
+dex_connectors/hackernews/_generated/config.py,sha256=Auq3eXNAkoGs7TwYBOJi7RdwmLCPaoV8DwAlvW1OjKw,364
+dex_connectors/hackernews/_generated/definitions.py,sha256=DrOM2bpfnI10aaPOxdPixHTekW87Ft9tDw8BtJmAFiA,1993
+dex_connectors/hackernews/_generated/models.py,sha256=nhwJqLAE5mKFqqJ4FvHB7JHjM5E6EN--iIi4jV_cims,4833
+dex_connectors/hackernews/_generated/steps.py,sha256=moI-sBrq8pgj4n5zwgpMEZFGVFy9mG_srxa9ZTfaZ30,5666
+dex_connectors/hackernews/_generated/timestamps.py,sha256=Z8VwrE60w-33InIMgEMLiMPTFyRjj6oBq8tUro8Ssi8,3164
+dex_connectors/hackernews/hackernewsmock/__init__.py,sha256=NEssHqCYtuN42tlwpJANIEf9bk0kLlN2fqdqNgkrQco,3732
+dex_connector_hackernews-0.1.0.dist-info/METADATA,sha256=UKL-FUQG6M74uptpkE8rNw_Lw91VNne-H9b7QmVDJ-0,1960
+dex_connector_hackernews-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dex_connector_hackernews-0.1.0.dist-info/RECORD,,

dex_connector_hackernews-0.1.0.dist-info/WHEEL

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

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_connectors/hackernews/_generated/__init__.py

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

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_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_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_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

dex_connectors/hackernews/_generated/timestamps.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# ruff: noqa
+"""Go time.Time JSON input parsing for generated connector models."""
+
+import re
+from datetime import datetime
+
+_GO_TIME = re.compile(
+    r"^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{1,2}):([0-9]{2}):([0-9]{2})"
+    r"(?:[.,]([0-9]+))?(Z|([+-])([0-9]{2}):([0-9]{2}))$"
+)
+
+
+def _parts(value: str, field_name: str) -> tuple[str, str, int, int]:
+    match = _GO_TIME.fullmatch(value)
+    if match is None:
+        raise ValueError(f"{field_name}: invalid Go time.Time JSON timestamp")
+    year, month, day, hour, minute, second, fraction, zone, sign, zone_hour, zone_minute = match.groups()
+    year_number, month_number, day_number = int(year), int(month), int(day)
+    is_leap = year_number % 4 == 0 and (year_number % 100 != 0 or year_number % 400 == 0)
+    month_days = (31, 29 if is_leap else 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+    if not (1 <= month_number <= 12 and 1 <= day_number <= month_days[month_number - 1]
+            and int(hour) <= 23 and int(minute) <= 59 and int(second) <= 59):
+        raise ValueError(f"{field_name}: invalid Go time.Time JSON timestamp")
+    offset_minutes = 0
+    if zone != "Z":
+        if int(zone_hour) > 24 or int(zone_minute) > 60:
+            raise ValueError(f"{field_name}: invalid Go time.Time JSON offset")
+        offset_minutes = (int(zone_hour) * 60 + int(zone_minute)) * (1 if sign == "+" else -1)
+    return year, f"{month}-{day}T{int(hour):02d}:{minute}:{second}", offset_minutes, int((fraction or "")[:9].ljust(9, "0"))
+
+
+def canonical_go_timestamp(value: str, field_name: str) -> str:
+    """Parse Go's accepted JSON timestamp spellings and format like MarshalJSON."""
+    year, clock, offset_minutes, nanoseconds = _parts(value, field_name)
+    fraction = f"{nanoseconds:09d}".rstrip("0")
+    if abs(offset_minutes) >= 24 * 60:
+        return value
+    offset = "Z" if offset_minutes == 0 else f"{'+' if offset_minutes > 0 else '-'}{abs(offset_minutes) // 60:02d}:{abs(offset_minutes) % 60:02d}"
+    return f"{year}-{clock}{'.' + fraction if fraction else ''}{offset}"
+
+
+def parse_go_datetime(value: str, field_name: str) -> datetime:
+    """Decode a Go timestamp only when Python datetime preserves its value."""
+    year, _, offset_minutes, nanoseconds = _parts(value, field_name)
+    if int(year) == 0 or nanoseconds % 1000 or abs(offset_minutes) >= 24 * 60:
+        raise ValueError(f"{field_name}: Go time.Time JSON timestamp cannot be represented exactly as datetime")
+    canonical = canonical_go_timestamp(value, field_name)
+    return datetime.fromisoformat(canonical.replace("Z", "+00:00"))
+
+
+def validate_go_datetime(value: datetime, field_name: str) -> datetime:
+    """Reject Python datetimes that cannot round-trip through Go JSON time."""
+    if not isinstance(value, datetime):
+        raise ValueError(f"{field_name}: expected a datetime or Go time.Time JSON timestamp")
+    offset = value.utcoffset() if value.tzinfo is not None else None
+    if offset is None or offset.total_seconds() % 60:
+        raise ValueError(f"{field_name}: datetime requires a whole-minute timezone offset")
+    return value

dex_connectors/hackernews/client.py

@@ -0,0 +1,357 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Hacker News public API reads and Go-compatible branch classification."""
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass as dataclass
+from datetime import UTC, datetime
+from datetime import timedelta as timedelta
+from typing import Any, TypeVar
+
+import httpx
+from dex_connectors.sdk import BranchDefinition as BranchDefinition
+from dex_connectors.sdk import (
+    Call,
+    Failure,
+    FailureKind,
+    OperationRef,
+    QueryAttempt,
+    QueryDefinition,
+    Receipt,
+)
+from dex_connectors.sdk import StepDefaults as StepDefaults
+from dex_connectors.sdk.providerhttp import (
+    BodyTooLargeError,
+    ProviderTransportError,
+    new_provider_http_client,
+    parse_retry_after,
+    read_bounded_body,
+    send_traced,
+    validate_base_url,
+)
+from dex_connectors.sdk.retry_policy import RetryPolicy as RetryPolicy
+
+from ._generated import definitions as _generated_definitions
+from ._generated.config import Config as _GeneratedConfig
+from ._generated.definitions import DEFECT as DEFECT
+from ._generated.definitions import FOUND as FOUND
+from ._generated.definitions import GET_ITEM_OPERATION_ID as GET_ITEM_OPERATION_ID
+from ._generated.definitions import INVALID_RESPONSE as INVALID_RESPONSE
+from ._generated.definitions import LIST_STORY_IDS_OPERATION_ID as LIST_STORY_IDS_OPERATION_ID
+from ._generated.definitions import LISTED as LISTED
+from ._generated.definitions import NOT_FOUND as NOT_FOUND
+from ._generated.definitions import PROVIDER_REJECTED as PROVIDER_REJECTED
+from .models import GetItemInput, Item, ListStoryIDsInput, StoryIDs
+
+CONNECTOR_ID = "hackernews"
+FAILURE_PROVIDER = "hacker-news"
+FEEDS = ("top", "best", "new", "ask", "show")
+ITEM_TYPES = ("story", "comment", "job", "poll", "pollopt")
+_DEFAULT_BASE_URL = "https://hacker-news.firebaseio.com/v0"
+_DEFAULT_TIMEOUT_SECONDS = 15
+_DEFAULT_MAX_RESPONSE_BYTES = 1_048_576
+
+LIST_STORY_IDS_DEFINITION = QueryDefinition(
+    OperationRef(CONNECTOR_ID, LIST_STORY_IDS_OPERATION_ID),
+    _generated_definitions.LIST_STORY_IDS_DEFINITION.branches or (),
+    _generated_definitions.LIST_STORY_IDS_DEFINITION.step_defaults,
+)
+GET_ITEM_DEFINITION = QueryDefinition(
+    OperationRef(CONNECTOR_ID, GET_ITEM_OPERATION_ID),
+    _generated_definitions.GET_ITEM_DEFINITION.branches or (),
+    _generated_definitions.GET_ITEM_DEFINITION.step_defaults,
+)
+
+Output = TypeVar("Output")
+
+
+class Config(_GeneratedConfig):
+    """Hacker News HTTP settings; zero or blank values use manifest defaults."""
+
+    __slots__ = ()
+
+
+class Client:
+    """One redirect-safe HTTP client for the public, unauthenticated API."""
+
+    def __init__(self, config: Config, http_client: httpx.AsyncClient | None = None) -> None:
+        if config is None:
+            raise ValueError("Hacker News configuration is required")
+        if config.timeout_seconds < 0 or config.max_response_bytes < 0:
+            raise ValueError("Hacker News timeout and maxResponseBytes must be positive")
+        self.base_url = validate_base_url(config.base_url or _DEFAULT_BASE_URL)
+        self.max_response_bytes = config.max_response_bytes or _DEFAULT_MAX_RESPONSE_BYTES
+        self.http_client = http_client or new_provider_http_client(
+            config.timeout_seconds or _DEFAULT_TIMEOUT_SECONDS
+        )
+
+    def list_story_ids(self) -> "ListStoryIDsOperation":
+        """Bind the feed snapshot Query to this client."""
+        return ListStoryIDsOperation(self)
+
+    def get_item(self) -> "GetItemOperation":
+        """Bind the item Query to this client."""
+        return GetItemOperation(self)
+
+    async def aclose(self) -> None:
+        """Close the owned provider HTTP client after application shutdown."""
+        await self.http_client.aclose()
+
+    async def get_json(
+        self, operation: str, path: str, empty: Output, decode: Callable[[bytes], QueryAttempt[Output]]
+    ) -> QueryAttempt[Output]:
+        """Send one GET and classify it exactly like the Go getJSON helper."""
+        try:
+            request = self.http_client.build_request(
+                "GET",
+                self.base_url + path,
+                headers={"Accept": "application/json", "User-Agent": "superdurable-hacker-news-daily/0.1"},
+            )
+        except (httpx.HTTPError, ValueError):
+            return _failed(
+                operation,
+                DEFECT,
+                empty,
+                FailureKind.VALIDATION,
+                "Hacker News request configuration is invalid",
+            )
+        try:
+            response, _ = await send_traced(self.http_client, request)
+        except ProviderTransportError:
+            return _retry(operation, FailureKind.AVAILABILITY, "Hacker News request failed", 0)
+        try:
+            status = response.status_code
+            if status in (408, 429) or status >= 500:
+                kind = FailureKind.RATE_LIMIT if status == 429 else FailureKind.AVAILABILITY
+                retry_after = parse_retry_after(response.headers.get("Retry-After", ""), datetime.now(UTC))
+                return _retry(operation, kind, "Hacker News is temporarily unavailable", retry_after)
+            if status == 404 and operation == GET_ITEM_OPERATION_ID:
+                return _failed(
+                    operation, NOT_FOUND, empty, FailureKind.NOT_FOUND, "Hacker News resource was not found"
+                )
+            if status != 200:
+                return _failed(
+                    operation,
+                    PROVIDER_REJECTED,
+                    empty,
+                    FailureKind.PROVIDER_REJECTION,
+                    "Hacker News rejected the request",
+                )
+            try:
+                body = await read_bounded_body(response, self.max_response_bytes)
+            except BodyTooLargeError:
+                return _failed(
+                    operation,
+                    INVALID_RESPONSE,
+                    empty,
+                    FailureKind.RESPONSE_TOO_LARGE,
+                    "Hacker News response exceeded the configured limit",
+                )
+            except ProviderTransportError:
+                return _retry(operation, FailureKind.AVAILABILITY, "Hacker News response was interrupted", 0)
+            return decode(body)
+        finally:
+            await response.aclose()
+
+
+class ListStoryIDsOperation:
+    """Read a bounded snapshot of one Hacker News feed."""
+
+    def __init__(self, client: Client) -> None:
+        if client is None:
+            raise ValueError("Hacker News client is required")
+        self.client = client
+
+    def definition(self) -> QueryDefinition:
+        """Return manifest identity, branches, and retry defaults."""
+        return LIST_STORY_IDS_DEFINITION
+
+    async def invoke(self, call: Call, input: ListStoryIDsInput) -> QueryAttempt[StoryIDs]:
+        """Validate the feed and limit, read once, then select a branch or safe retry."""
+        operation = LIST_STORY_IDS_OPERATION_ID
+        if (
+            not isinstance(input, ListStoryIDsInput)
+            or not isinstance(input.feed, str)
+            or type(input.limit) is not int
+        ):
+            return _failed(
+                operation, DEFECT, StoryIDs(), FailureKind.VALIDATION, "feed and limit are invalid"
+            )
+        feed = input.feed or "top"
+        limit = input.limit or 50
+        if feed not in FEEDS:
+            return _failed(
+                operation,
+                DEFECT,
+                StoryIDs(),
+                FailureKind.VALIDATION,
+                "feed must be top, best, new, ask, or show",
+            )
+        if not 1 <= limit <= 500:
+            return _failed(
+                operation, DEFECT, StoryIDs(), FailureKind.VALIDATION, "limit must be from 1 through 500"
+            )
+        return await self.client.get_json(
+            operation, f"/{feed}stories.json", StoryIDs(), lambda body: _decode_story_ids(body, limit)
+        )
+
+
+class GetItemOperation:
+    """Read one public Hacker News item."""
+
+    def __init__(self, client: Client) -> None:
+        if client is None:
+            raise ValueError("Hacker News client is required")
+        self.client = client
+
+    def definition(self) -> QueryDefinition:
+        """Return manifest identity, branches, and retry defaults."""
+        return GET_ITEM_DEFINITION
+
+    async def invoke(self, call: Call, input: GetItemInput) -> QueryAttempt[Item]:
+        """Validate the item ID, read once, then select a branch or safe retry."""
+        operation = GET_ITEM_OPERATION_ID
+        if not isinstance(input, GetItemInput) or type(input.id) is not int or input.id <= 0:
+            return _failed(operation, DEFECT, Item(), FailureKind.VALIDATION, "item ID must be positive")
+        requested = input.id
+        return await self.client.get_json(
+            operation, f"/item/{requested}.json", Item(), lambda body: _decode_item(body, requested)
+        )
+
+
+def _failed(
+    operation: str, branch: str, value: Output, kind: FailureKind, message: str
+) -> QueryAttempt[Output]:
+    return QueryAttempt.branch_result(
+        branch, value, Receipt(), Failure(kind, FAILURE_PROVIDER, operation, message)
+    )
+
+
+def _retry(operation: str, kind: FailureKind, message: str, after_seconds: float) -> QueryAttempt[Any]:
+    return QueryAttempt.retry(Failure(kind, FAILURE_PROVIDER, operation, message), after_seconds)
+
+
+def _decode_story_ids(body: bytes, limit: int) -> QueryAttempt[StoryIDs]:
+    operation = LIST_STORY_IDS_OPERATION_ID
+    try:
+        ids = json.loads(body)
+        if not isinstance(ids, list) or any(type(value) is not int for value in ids):
+            raise ValueError
+    except (ValueError, UnicodeDecodeError):
+        return _failed(
+            operation,
+            INVALID_RESPONSE,
+            StoryIDs(),
+            FailureKind.PROTOCOL,
+            "Hacker News returned an invalid feed",
+        )
+    if any(value <= 0 for value in ids):
+        return _failed(
+            operation,
+            INVALID_RESPONSE,
+            StoryIDs(),
+            FailureKind.PROTOCOL,
+            "Hacker News returned an invalid item ID",
+        )
+    return QueryAttempt.branch_result(
+        LISTED, StoryIDs(tuple(ids[:limit]), len(ids) > limit, datetime.now(UTC)), Receipt()
+    )
+
+
+def _decode_item(body: bytes, requested: int) -> QueryAttempt[Item]:
+    operation = GET_ITEM_OPERATION_ID
+    try:
+        document = json.loads(body)
+        item = None if document is None else _item(document)
+    except (ValueError, TypeError, UnicodeDecodeError):
+        return _failed(
+            operation,
+            INVALID_RESPONSE,
+            Item(),
+            FailureKind.PROTOCOL,
+            "Hacker News returned malformed item JSON",
+        )
+    if item is None or item.deleted or item.dead:
+        return _failed(
+            operation, NOT_FOUND, Item(), FailureKind.NOT_FOUND, "Hacker News item is deleted or dead"
+        )
+    if item.id != requested:
+        return _failed(
+            operation,
+            INVALID_RESPONSE,
+            Item(),
+            FailureKind.PROTOCOL,
+            "Hacker News returned a different item ID",
+        )
+    if item.type not in ITEM_TYPES:
+        return _failed(
+            operation,
+            INVALID_RESPONSE,
+            Item(),
+            FailureKind.PROTOCOL,
+            "Hacker News returned an unknown item type",
+        )
+    if any(kid <= 0 for kid in item.kids):
+        return _failed(
+            operation,
+            INVALID_RESPONSE,
+            Item(),
+            FailureKind.PROTOCOL,
+            "Hacker News returned an invalid child ID",
+        )
+    return QueryAttempt.branch_result(FOUND, item, Receipt())
+
+
+def _item(document: Any) -> Item:
+    if not isinstance(document, dict):
+        raise ValueError
+    kids = document.get("kids")
+    if kids is None:
+        kids = []
+    if not isinstance(kids, list) or any(type(kid) is not int for kid in kids):
+        raise ValueError
+    item_id = _integer(document, "id")
+    return Item(
+        id=item_id,
+        type=_string(document, "type"),
+        discussion_url=f"https://news.ycombinator.com/item?id={item_id}",
+        by=_string(document, "by"),
+        time=_integer(document, "time"),
+        title=_string(document, "title"),
+        text_html=_string(document, "text"),
+        url=_string(document, "url"),
+        score=_integer(document, "score"),
+        descendants=_integer(document, "descendants"),
+        parent=_integer(document, "parent"),
+        kids=tuple(kids),
+        deleted=_boolean(document, "deleted"),
+        dead=_boolean(document, "dead"),
+    )
+
+
+def _string(document: dict[str, Any], name: str) -> str:
+    value = document.get(name)
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise ValueError
+    return value
+
+
+def _integer(document: dict[str, Any], name: str) -> int:
+    value = document.get(name)
+    if value is None:
+        return 0
+    if type(value) is not int:
+        raise ValueError
+    return value
+
+
+def _boolean(document: dict[str, Any], name: str) -> bool:
+    value = document.get(name)
+    if value is None:
+        return False
+    if not isinstance(value, bool):
+        raise ValueError
+    return value

dex_connectors/hackernews/connection.py

@@ -0,0 +1,109 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# connectorctl: handwritten facade
+"""Hacker News connection for a named project connection."""
+
+from typing import Any
+
+import httpx
+from dex_connectors.sdk import ConnectionRef, Query
+from dex_connectors.sdk.projectconfig import LoadedProject
+
+from .client import CONNECTOR_ID, GET_ITEM_DEFINITION, LIST_STORY_IDS_DEFINITION, Client, Config
+from .models import GetItemInput, Item, ListStoryIDsInput, StoryIDs
+
+
+class Connection:
+    """Nonserializable Hacker News operation bindings for a named project connection."""
+
+    __slots__ = ("_list_story_ids", "_get_item", "_client", "reference")
+
+    def __init__(
+        self,
+        reference: ConnectionRef,
+        list_story_ids: Query[ListStoryIDsInput, StoryIDs],
+        get_item: Query[GetItemInput, Item],
+        client: Client | None = None,
+    ) -> None:
+        reference.validate()
+        if reference.provider != CONNECTOR_ID or list_story_ids is None or get_item is None:
+            raise ValueError("Hacker News connection provider and operations are required")
+        if (
+            list_story_ids.definition().operation != LIST_STORY_IDS_DEFINITION.operation
+            or get_item.definition().operation != GET_ITEM_DEFINITION.operation
+        ):
+            raise ValueError("Hacker News connection operation identity differs")
+        self.reference = reference
+        self._list_story_ids = list_story_ids
+        self._get_item = get_item
+        self._client = client
+
+    def list_story_ids(self) -> Query[ListStoryIDsInput, StoryIDs]:
+        """Return the feed snapshot Query used by an application Step."""
+        return self._list_story_ids
+
+    def get_item(self) -> Query[GetItemInput, Item]:
+        """Return the item Query used by an application Step."""
+        return self._get_item
+
+    async def aclose(self) -> None:
+        """Close the owned provider transport after Worker shutdown."""
+        if self._client is not None:
+            await self._client.aclose()
+
+    def __repr__(self) -> str:
+        """Keep provider transport out of logs."""
+        return "hackernews.Connection([REDACTED])"
+
+    def __reduce__(self) -> tuple[object, ...]:
+        """Prevent a live connection from entering durable Flow state."""
+        raise TypeError("Hacker News connections cannot be serialized")
+
+
+def new_connection(client: Client, reference: ConnectionRef) -> Connection:
+    """Bind a client to an explicit logical connection reference."""
+    if client is None:
+        raise ValueError("Hacker News client is required")
+    return Connection(reference, client.list_story_ids(), client.get_item(), client)
+
+
+def new_connection_with_operations(
+    list_story_ids: Query[ListStoryIDsInput, StoryIDs],
+    get_item: Query[GetItemInput, Item],
+    reference: ConnectionRef,
+) -> Connection:
+    """Bind mock operations to the same connection identity as the real provider."""
+    return Connection(reference, list_story_ids, get_item)
+
+
+def new_project_connection(
+    project: LoadedProject, connection_name: str, http_client: httpx.AsyncClient | None = None
+) -> Connection:
+    """Open the declared connection settings; the public API needs no credentials."""
+    if project is None:
+        raise ValueError("Hacker News connection requires loaded project configuration")
+    reference = ConnectionRef(CONNECTOR_ID, connection_name)
+    reference.validate()
+    matching = [
+        entry
+        for entry in project.configuration.connections
+        if entry.connector_id == CONNECTOR_ID and entry.connection_name == connection_name
+    ]
+    if len(matching) != 1:
+        raise ValueError("Hacker News project connection is missing or duplicated")
+    if matching[0].provider != CONNECTOR_ID:
+        raise ValueError("Hacker News project connection provider differs")
+    return new_connection(Client(_decode_config(matching[0].configuration), http_client), reference)
+
+
+def _decode_config(value: dict[str, Any]) -> Config:
+    if set(value) - {"baseUrl", "timeout", "maxResponseBytes"}:
+        raise ValueError("Hacker News configuration has unknown fields")
+    base_url = value.get("baseUrl", "")
+    timeout = value.get("timeout", 0)
+    max_response_bytes = value.get("maxResponseBytes", 0)
+    if not isinstance(base_url, str):
+        raise ValueError("Hacker News configuration baseUrl must be a string")
+    if type(timeout) is not int or type(max_response_bytes) is not int:
+        raise ValueError("Hacker News configuration timeout and maxResponseBytes must be integers")
+    return Config(base_url, timeout / 1_000_000_000, max_response_bytes)

dex_connectors/hackernews/dex-connector.json

@@ -0,0 +1,82 @@
+{
+  "connectorId": "hacker-news-daily",
+  "releaseTag": "connectors/hackernews/go/v0.23.0",
+  "package": {
+    "ecosystem": "pypi",
+    "name": "dex-connector-hackernews",
+    "version": "0.1.0"
+  },
+  "factories": [
+    {
+      "name": "new_list_story_ids_step",
+      "kind": "query",
+      "operationId": "listStoryIDs",
+      "fields": {
+        "stepType": "step_type",
+        "annotations": "annotations",
+        "connectionName": "connection_name",
+        "resultAttribute": "result_attribute"
+      },
+      "branches": [
+        {
+          "id": "listed",
+          "field": "listed",
+          "optional": false
+        },
+        {
+          "id": "providerRejected",
+          "field": "provider_rejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalid_response",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "field": "defect",
+          "optional": true
+        }
+      ]
+    },
+    {
+      "name": "new_get_item_step",
+      "kind": "query",
+      "operationId": "getItem",
+      "fields": {
+        "stepType": "step_type",
+        "annotations": "annotations",
+        "connectionName": "connection_name",
+        "resultAttribute": "result_attribute"
+      },
+      "branches": [
+        {
+          "id": "found",
+          "field": "found",
+          "optional": false
+        },
+        {
+          "id": "notFound",
+          "field": "not_found",
+          "optional": true
+        },
+        {
+          "id": "providerRejected",
+          "field": "provider_rejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalid_response",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "field": "defect",
+          "optional": true
+        }
+      ]
+    }
+  ]
+}

dex_connectors/hackernews/hackernewsmock/__init__.py

@@ -0,0 +1,119 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# connectorctl: handwritten facade
+"""Manifest-backed Hacker News scripts for consuming Flow tests."""
+
+from datetime import UTC, datetime
+
+from dex_connectors.sdk import ConnectionRef, Failure, FailureKind
+from dex_connectors.sdk.connectormock import Case, Query
+
+from ..client import (
+    CONNECTOR_ID,
+    FAILURE_PROVIDER,
+    FOUND,
+    GET_ITEM_DEFINITION,
+    LIST_STORY_IDS_DEFINITION,
+    LISTED,
+    NOT_FOUND,
+    PROVIDER_REJECTED,
+)
+from ..connection import Connection, new_connection_with_operations
+from ..models import GetItemInput, Item, ListStoryIDsInput, StoryIDs
+
+
+def list_story_ids_listed(value: StoryIDs, failure: Failure | None = None) -> Case[StoryIDs]:
+    """Script the successful listed route."""
+    return Case.branch_result(LISTED, value, failure)
+
+
+def list_story_ids_developer_feed() -> Case[StoryIDs]:
+    """Return the manifest's developerFeed answer."""
+    return list_story_ids_listed(StoryIDs((42001,), True, datetime(2026, 10, 26, 12, tzinfo=UTC)))
+
+
+def list_story_ids_feed_rejected() -> Case[StoryIDs]:
+    """Return the manifest's feedRejected answer."""
+    return Case.branch_result(
+        PROVIDER_REJECTED,
+        StoryIDs(),
+        Failure(
+            FailureKind.PROVIDER_REJECTION,
+            FAILURE_PROVIDER,
+            "listStoryIDs",
+            "Hacker News rejected the feed request.",
+        ),
+    )
+
+
+def get_item_found(value: Item, failure: Failure | None = None) -> Case[Item]:
+    """Script the successful found route."""
+    return Case.branch_result(FOUND, value, failure)
+
+
+def get_item_compiler_story() -> Case[Item]:
+    """Return the manifest's compilerStory answer."""
+    return get_item_found(
+        Item(
+            id=42001,
+            type="story",
+            discussion_url="https://news.ycombinator.com/item?id=42001",
+            by="compilerdev",
+            time=1793016000,
+            title="A compiler release",
+            url="https://example.com/compiler",
+            score=100,
+        )
+    )
+
+
+def get_item_missing() -> Case[Item]:
+    """Return the manifest's itemMissing answer."""
+    return Case.branch_result(
+        NOT_FOUND,
+        Item(),
+        Failure(FailureKind.NOT_FOUND, FAILURE_PROVIDER, "getItem", "Hacker News item is deleted or dead."),
+    )
+
+
+def get_item_rejected() -> Case[Item]:
+    """Return the manifest's itemRejected answer."""
+    return Case.branch_result(
+        PROVIDER_REJECTED,
+        Item(),
+        Failure(
+            FailureKind.PROVIDER_REJECTION,
+            FAILURE_PROVIDER,
+            "getItem",
+            "Hacker News rejected the item request.",
+        ),
+    )
+
+
+class Mock:
+    """Script Hacker News Queries, defaulting to their manifest answers."""
+
+    def __init__(self, connection_name: str = "hackernews") -> None:
+        self.list_story_ids_script: Query[ListStoryIDsInput, StoryIDs] = Query(LIST_STORY_IDS_DEFINITION)
+        self.list_story_ids_script.default(list_story_ids_developer_feed())
+        self.get_item_script: Query[GetItemInput, Item] = Query(GET_ITEM_DEFINITION)
+        self.get_item_script.default(get_item_compiler_story())
+        self._connection = new_connection_with_operations(
+            self.list_story_ids_script, self.get_item_script, ConnectionRef(CONNECTOR_ID, connection_name)
+        )
+
+    def connection(self) -> Connection:
+        """Return this mock's named connection for Step registration."""
+        return self._connection
+
+
+__all__ = [
+    "Mock",
+    "list_story_ids_listed",
+    "list_story_ids_developer_feed",
+    "list_story_ids_feed_rejected",
+    "get_item_found",
+    "get_item_compiler_story",
+    "get_item_missing",
+    "get_item_rejected",
+]

dex_connectors/hackernews/models.py

@@ -0,0 +1,36 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Typed Hacker News feed snapshots and items."""
+
+from dataclasses import dataclass, field
+
+from ._generated.models import GetItemInput as GetItemInput
+from ._generated.models import ListStoryIDsInput as ListStoryIDsInput
+from ._generated.models import StoryIDs as StoryIDs
+
+
+@dataclass(frozen=True, slots=True)
+class Item:
+    """Public story, comment, job, poll, or poll option; text_html is untrusted provider HTML."""
+
+    id: int = 0
+    type: str = ""
+    discussion_url: str = field(default="", metadata={"dex_json_name": "discussionUrl"})
+    by: str = field(default="", metadata={"dex_json_omit_default": True})
+    time: int = field(default=0, metadata={"dex_json_omit_default": True})
+    title: str = field(default="", metadata={"dex_json_omit_default": True})
+    text_html: str = field(default="", metadata={"dex_json_name": "text", "dex_json_omit_default": True})
+    url: str = field(default="", metadata={"dex_json_omit_default": True})
+    score: int = field(default=0, metadata={"dex_json_omit_default": True})
+    descendants: int = field(default=0, metadata={"dex_json_omit_default": True})
+    parent: int = field(default=0, metadata={"dex_json_omit_default": True})
+    kids: tuple[int, ...] = field(default=(), metadata={"dex_json_omit_default": True})
+    deleted: bool = field(default=False, metadata={"dex_json_omit_default": True})
+    dead: bool = field(default=False, metadata={"dex_json_omit_default": True})
+
+
+ListStoryIDsInput.__doc__ = (
+    "Feed (top, best, new, ask, or show; blank means top) and limit (zero means 50, at most 500)."
+)
+StoryIDs.__doc__ = "Item IDs in provider order, whether the feed held more, and when the snapshot was read."
+GetItemInput.__doc__ = "Positive Hacker News item ID."

dex_connectors/hackernews/steps.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Public operation-specific Step factories from connector.yaml."""
+
+from collections.abc import Callable as Callable
+from collections.abc import Mapping as Mapping
+from typing import TypeVar as TypeVar
+
+import dex as dex
+from dex_connectors.sdk import QueryResult as QueryResult
+from dex_connectors.sdk import QueryStep as QueryStep
+from dex_connectors.sdk import QueryStepConfig as QueryStepConfig
+from dex_connectors.sdk import StepAnnotations as StepAnnotations
+
+from ._generated.steps import (
+    StepInput as StepInput,
+)
+from ._generated.steps import (
+    new_get_item_step as new_get_item_step,
+)
+from ._generated.steps import (
+    new_list_story_ids_step as new_list_story_ids_step,
+)
+from .connection import Connection as Connection
+from .models import GetItemInput as GetItemInput
+from .models import Item as Item
+from .models import ListStoryIDsInput as ListStoryIDsInput
+from .models import StoryIDs as StoryIDs
+
+BranchTarget = TypeVar("BranchTarget")
+
+new_list_story_ids_step.__doc__ = (
+    "Create the typed feed snapshot Step; unwired optional outcomes fail the Flow."
+)
+new_get_item_step.__doc__ = "Create the typed item Step; unwired optional outcomes fail the Flow."