@superdurable/connector-hackernews 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Super Durable
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# Hacker News TypeScript connector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The public Hacker News API connector reads feed IDs and item details with Dex Query Steps. Install `@superdurable/connector-hackernews` and declare a `hacker-news` connection named `hackernews-public` in your Dex project. The checked-in [top-story example](examples/top-story/README.md) shows the typed Flow and Worker.
+
+`HackerNewsClient` accepts `baseUrl`, `timeoutMs`, and `maxResponseBytes`; omitted values use the manifest defaults. `newProjectConnection` reads the named Dex project connection, including the manifest `timeout` in nanoseconds. The provider is public, so no credential is required. Provider calls occur only inside Step execution. `listStoryIDs` accepts top, best, new, ask, or show and a limit from 1 to 500. `getItem` reads one positive item ID and supplies its Hacker News discussion URL. Missing, deleted, and dead items select `notFound`; rate limits and availability failures retry.
+
+Run `npm run check` for package tests, type checking, lint, and build. Conformance fixtures replay Go-recorded provider exchanges in both TypeScript and Python. The example integration needs a running `dexcli dev` stack; live Hacker News behavior has not been verified.

package/dex-connector.json

@@ -0,0 +1,134 @@
+{
+  "connectorId": "hacker-news-daily",
+  "releaseTag": "connectors/hackernews/go/v0.23.0",
+  "package": {
+    "ecosystem": "npm",
+    "name": "@superdurable/connector-hackernews",
+    "version": "0.2.0"
+  },
+  "factories": [
+    {
+      "name": "newListStoryIDsStep",
+      "kind": "query",
+      "operationId": "listStoryIDs",
+      "inputType": "ListStoryIDsInput",
+      "description": "List current Hacker News story IDs in feed order. Choose feed top, best, new, ask (Ask HN), or show (Show HN), and limit from 1 to 500. Read each returned ID as a Hacker News item for its title and links.",
+      "agent": {
+        "exposed": true,
+        "branches": {
+          "defect": "rejected",
+          "providerRejected": "rejected"
+        }
+      },
+      "fields": {
+        "stepType": "stepType",
+        "annotations": "annotations",
+        "connectionName": "connectionName",
+        "resultAttribute": "resultAttribute"
+      },
+      "branches": [
+        {
+          "id": "listed",
+          "field": "listed",
+          "optional": false
+        },
+        {
+          "id": "providerRejected",
+          "field": "providerRejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalidResponse",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "field": "defect",
+          "optional": true
+        }
+      ],
+      "inputSchema": {
+        "additionalProperties": false,
+        "description": "ListStoryIDsInput selects one feed snapshot. It does not select a historical time window.",
+        "properties": {
+          "feed": {
+            "description": "Feed is top, best, new, ask, or show. Empty selects top.",
+            "type": "string"
+          },
+          "limit": {
+            "description": "Limit bounds returned IDs from 1 through 500. Zero selects 50.",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "feed",
+          "limit"
+        ],
+        "type": "object"
+      }
+    },
+    {
+      "name": "newGetItemStep",
+      "kind": "query",
+      "operationId": "getItem",
+      "inputType": "GetItemInput",
+      "description": "Read one public Hacker News story, comment, job, or poll by its positive item ID. Returns title, author, score, source URL, discussion URL, text as untrusted HTML, and child comment IDs to read next.",
+      "agent": {
+        "exposed": true,
+        "branches": {
+          "defect": "rejected",
+          "notFound": "rejected",
+          "providerRejected": "rejected"
+        }
+      },
+      "fields": {
+        "stepType": "stepType",
+        "annotations": "annotations",
+        "connectionName": "connectionName",
+        "resultAttribute": "resultAttribute"
+      },
+      "branches": [
+        {
+          "id": "found",
+          "field": "found",
+          "optional": false
+        },
+        {
+          "id": "notFound",
+          "field": "notFound",
+          "optional": true
+        },
+        {
+          "id": "providerRejected",
+          "field": "providerRejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalidResponse",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "field": "defect",
+          "optional": true
+        }
+      ],
+      "inputSchema": {
+        "additionalProperties": false,
+        "description": "GetItemInput identifies one story, comment, job, poll, or poll option.",
+        "properties": {
+          "id": {
+            "description": "ID is a positive Hacker News item ID.",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "type": "object"
+      }
+    }
+  ]
+}

package/dist/chunk-23APJHSI.js

@@ -0,0 +1,165 @@
+// src/generated/models.ts
+import { z } from "zod";
+var goTimeJSONPattern = /^(\d{4})-(\d{2})-(\d{2})T(\d{1,2}):(\d{2}):(\d{2})(?:[.,](\d+))?(Z|([+-])(\d{2}):(\d{2}))$/;
+function isGoTimeJSON(value) {
+  const match = goTimeJSONPattern.exec(value);
+  if (!match) return false;
+  const [, yearText, monthText, dayText, hourText, minuteText, secondText, , zone, , zoneHourText, zoneMinuteText] = match;
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  const isLeap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const monthDays = [31, isLeap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return month >= 1 && month <= 12 && day >= 1 && day <= monthDays[month - 1] && Number(hourText) <= 23 && Number(minuteText) <= 59 && Number(secondText) <= 59 && (zone === "Z" || Number(zoneHourText) <= 24 && Number(zoneMinuteText) <= 60);
+}
+function canonicalGoTimeJSON(value) {
+  const match = goTimeJSONPattern.exec(value);
+  const [, year, month, day, hour, minute, second, fraction, zone, sign, zoneHour, zoneMinute] = match;
+  const clock = year + "-" + month + "-" + day + "T" + hour.padStart(2, "0") + ":" + minute + ":" + second;
+  const digits = (fraction ?? "").slice(0, 9).replace(/0+$/, "");
+  const offsetMinutes = zone === "Z" ? 0 : (Number(zoneHour) * 60 + Number(zoneMinute)) * (sign === "+" ? 1 : -1);
+  if (Math.abs(offsetMinutes) >= 1440) return value;
+  const offset = offsetMinutes === 0 ? "Z" : (offsetMinutes > 0 ? "+" : "-") + String(Math.floor(Math.abs(offsetMinutes) / 60)).padStart(2, "0") + ":" + String(Math.abs(offsetMinutes) % 60).padStart(2, "0");
+  return clock + (digits ? "." + digits : "") + offset;
+}
+var GoTimeJSONSchema = z.string().refine(isGoTimeJSON, "invalid Go time.Time JSON timestamp").transform(canonicalGoTimeJSON);
+var ConfigSchema = z.object({
+  "baseUrl": z.string().optional(),
+  "timeoutMs": z.number().int().optional(),
+  "maxResponseBytes": z.number().int().optional()
+});
+var ListStoryIDsInputSchema = z.strictObject({
+  "feed": z.string(),
+  "limit": z.number().int()
+});
+var StoryIDsSchema = z.strictObject({
+  "ids": z.array(z.number().int()).nullable(),
+  "hasMore": z.boolean(),
+  "observedAt": GoTimeJSONSchema
+});
+var GetItemInputSchema = z.strictObject({
+  "id": z.number().int()
+});
+var ItemSchema = z.strictObject({
+  "id": z.number().int(),
+  "type": z.string(),
+  "by": z.string().optional(),
+  "time": z.number().int().optional(),
+  "title": z.string().optional(),
+  "text": z.string().optional(),
+  "url": z.string().optional(),
+  "discussionUrl": z.string(),
+  "score": z.number().int().optional(),
+  "descendants": z.number().int().optional(),
+  "parent": z.number().int().optional(),
+  "kids": z.array(z.number().int()).optional(),
+  "deleted": z.boolean().optional(),
+  "dead": z.boolean().optional()
+});
+
+// src/generated/definitions.ts
+var ConnectorID = "hacker-news-daily";
+var ProviderID = "hacker-news";
+var ListStoryIDsBranch = {
+  Listed: "listed",
+  ProviderRejected: "providerRejected",
+  InvalidResponse: "invalidResponse",
+  Defect: "defect"
+};
+var ListStoryIDsBranchListed = ListStoryIDsBranch.Listed;
+var ListStoryIDsBranchProviderRejected = ListStoryIDsBranch.ProviderRejected;
+var ListStoryIDsBranchInvalidResponse = ListStoryIDsBranch.InvalidResponse;
+var ListStoryIDsBranchDefect = ListStoryIDsBranch.Defect;
+var ListStoryIDsDefinition = {
+  operation: { connectorId: ConnectorID, operationId: "listStoryIDs" },
+  branches: [
+    { id: "listed", description: "The feed snapshot was read." },
+    { id: "providerRejected", description: "Hacker News rejected the request.", optional: true },
+    { id: "invalidResponse", description: "Hacker News returned malformed or oversized data.", optional: true },
+    { id: "defect", description: "Local input or connection configuration is invalid.", optional: true }
+  ],
+  stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "async", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 0, totalDurationMs: 39e5 } }
+};
+var ListStoryIDsMetadata = { kind: "query", idempotency: "none", authorization: "none" };
+var GetItemBranch = {
+  Found: "found",
+  NotFound: "notFound",
+  ProviderRejected: "providerRejected",
+  InvalidResponse: "invalidResponse",
+  Defect: "defect"
+};
+var GetItemBranchFound = GetItemBranch.Found;
+var GetItemBranchNotFound = GetItemBranch.NotFound;
+var GetItemBranchProviderRejected = GetItemBranch.ProviderRejected;
+var GetItemBranchInvalidResponse = GetItemBranch.InvalidResponse;
+var GetItemBranchDefect = GetItemBranch.Defect;
+var GetItemDefinition = {
+  operation: { connectorId: ConnectorID, operationId: "getItem" },
+  branches: [
+    { id: "found", description: "The public item was read." },
+    { id: "notFound", description: "The item is missing, deleted, or dead.", optional: true },
+    { id: "providerRejected", description: "Hacker News rejected the request.", optional: true },
+    { id: "invalidResponse", description: "Hacker News returned malformed or oversized data.", optional: true },
+    { id: "defect", description: "Local input or connection configuration is invalid.", optional: true }
+  ],
+  stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "async", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 0, totalDurationMs: 39e5 } }
+};
+var GetItemMetadata = { kind: "query", idempotency: "none", authorization: "none" };
+
+// src/generated/connection.ts
+import { ConnectionRefSchema } from "@superdurable/connectors-sdk";
+var Connection = class {
+  /** Stable provider and connection name. */
+  reference;
+  /** Bound provider operations. */
+  operations;
+  /** Validate a reference and bind operations. */
+  constructor(reference, operations) {
+    this.reference = ConnectionRefSchema.parse(reference);
+    if (this.reference.provider !== ProviderID) throw new TypeError("connection provider differs from the manifest");
+    if (!operations) throw new TypeError("connector operations are required");
+    this.operations = operations;
+  }
+};
+function newConnection(client, reference) {
+  if (!client) throw new TypeError("connector client is required");
+  return new Connection(reference, client);
+}
+function newConnectionWithOperations(operations, reference) {
+  return new Connection(reference, operations);
+}
+function newProjectConnection(project, connectionName, createClient) {
+  if (!project) throw new TypeError("loaded project is required");
+  const reference = ConnectionRefSchema.parse({ provider: ProviderID, name: connectionName });
+  const selected = project.configuration.connections.find((entry) => entry.connectorId === ConnectorID && entry.connectionName === connectionName);
+  if (!selected || selected.provider !== ProviderID) throw new TypeError("project connection is not configured");
+  return newConnection(createClient(project, connectionName), reference);
+}
+
+export {
+  ListStoryIDsInputSchema,
+  StoryIDsSchema,
+  GetItemInputSchema,
+  ItemSchema,
+  ConnectorID,
+  ProviderID,
+  ListStoryIDsBranch,
+  ListStoryIDsBranchListed,
+  ListStoryIDsBranchProviderRejected,
+  ListStoryIDsBranchInvalidResponse,
+  ListStoryIDsBranchDefect,
+  ListStoryIDsDefinition,
+  ListStoryIDsMetadata,
+  GetItemBranch,
+  GetItemBranchFound,
+  GetItemBranchNotFound,
+  GetItemBranchProviderRejected,
+  GetItemBranchInvalidResponse,
+  GetItemBranchDefect,
+  GetItemDefinition,
+  GetItemMetadata,
+  Connection,
+  newConnection,
+  newConnectionWithOperations,
+  newProjectConnection
+};

package/dist/connection-fC9QqgNx.d.ts

@@ -0,0 +1,100 @@
+import { Query, ConnectionRef } from '@superdurable/connectors-sdk';
+import { z } from 'zod';
+
+/** Connector configuration; omitted fields use manifest defaults. */
+interface Config {
+    /** Hacker News Firebase API base URL; this is a fixed public endpoint, so leave the field blank unless a loopback test server is being used. */
+    baseUrl?: string;
+    /** Maximum duration for one Hacker News HTTP request, using a positive Go duration such as 15s or 1m; leave blank for the displayed default. Runtime value in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum bytes accepted from one Hacker News response; enter a positive integer only to change the safety limit. Oversized responses select invalidResponse. */
+    maxResponseBytes?: number;
+}
+/** Private connector credentials resolved by the host. */
+interface Credentials {
+}
+/** ListStoryIDsInput selects one feed snapshot. It does not select a historical time window. */
+interface ListStoryIDsInput {
+    /** Feed is top, best, new, ask, or show. Empty selects top. */
+    "feed": string;
+    /** Limit bounds returned IDs from 1 through 500. Zero selects 50. */
+    "limit": number;
+}
+/** StoryIDs contains the start of a feed in the provider's current display order. */
+interface StoryIDs {
+    /** IDs contains at most the requested limit. Top stories can include jobs. */
+    "ids": Array<number> | null;
+    /** HasMore reports that the API returned more IDs than this operation retained. The API has no page cursor. */
+    "hasMore": boolean;
+    /** ObservedAt is the UTC time when this response was read. */
+    "observedAt": string;
+}
+/** GetItemInput identifies one story, comment, job, poll, or poll option. */
+interface GetItemInput {
+    /** ID is a positive Hacker News item ID. */
+    "id": number;
+}
+/** 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. */
+interface Item {
+    /** ID identifies this item. */
+    "id": number;
+    /** Type is story, comment, job, poll, or pollopt. */
+    "type": string;
+    /** By is the author's public username, when available. */
+    "by"?: string | undefined;
+    /** Time is the creation time in Unix seconds, when available. */
+    "time"?: number | undefined;
+    /** Title is the provider's title, which can contain HTML entities. */
+    "title"?: string | undefined;
+    /** TextHTML is the submitted story or comment body. Linked article content is not included. */
+    "text"?: string | undefined;
+    /** URL is the submitted external URL. Ask HN and other text posts may have no URL. */
+    "url"?: string | undefined;
+    /** DiscussionURL links directly to this story or comment on Hacker News. */
+    "discussionUrl": string;
+    /** Score is the story score. Hacker News does not expose comment scores. */
+    "score"?: number | undefined;
+    /** Descendants is the provider's comment count for a story or poll. */
+    "descendants"?: number | undefined;
+    /** Parent identifies a comment's parent item or a poll option's poll. */
+    "parent"?: number | undefined;
+    /** Kids contains child IDs in the provider's ranked display order. */
+    "kids"?: Array<number> | undefined;
+    /** Deleted reports a deleted item. GetItem selects notFound instead of returning a tombstone. */
+    "deleted"?: boolean | undefined;
+    /** Dead reports a moderated item. GetItem selects notFound instead of returning it. */
+    "dead"?: boolean | undefined;
+}
+/** Runtime validator for ListStoryIDsInput. */
+declare const ListStoryIDsInputSchema: z.ZodObject<{
+    feed: z.ZodString;
+    limit: z.ZodNumber;
+}, z.core.$strict>;
+/** Runtime validator for GetItemInput. */
+declare const GetItemInputSchema: z.ZodObject<{
+    id: z.ZodNumber;
+}, z.core.$strict>;
+
+/** Typed operations supplied by a client or mock. */
+interface Operations {
+    /** Invoke listStoryIDs through this connection. */
+    listStoryIDs(): Query<ListStoryIDsInput, StoryIDs>;
+    /** Invoke getItem through this connection. */
+    getItem(): Query<GetItemInput, Item>;
+}
+/** Named connector connection kept outside Flow state. */
+declare class Connection<BoundOperations = Operations> {
+    /** Stable provider and connection name. */
+    readonly reference: ConnectionRef;
+    /** Bound provider operations. */
+    readonly operations: BoundOperations;
+    /** Validate a reference and bind operations. */
+    constructor(reference: ConnectionRef, operations: BoundOperations);
+}
+/** Bind a client to a named connection. */
+declare function newConnection(client: Operations, reference: ConnectionRef): Connection;
+/** Bind scripted operations to a named connection. */
+declare function newConnectionWithOperations(operations: Operations, reference: ConnectionRef): Connection;
+
+export { Connection as C, type GetItemInput as G, type Item as I, type ListStoryIDsInput as L, type Operations as O, type StoryIDs as S, type Config as a, type Credentials as b, GetItemInputSchema as c, ListStoryIDsInputSchema as d, newConnectionWithOperations as e, newConnection as n };

package/dist/hackernewsmock.d.ts

@@ -0,0 +1,60 @@
+import { MockQuery, Case } from '@superdurable/connectors-sdk/connectormock';
+import { Failure } from '@superdurable/connectors-sdk';
+import { O as Operations, C as Connection, L as ListStoryIDsInput, S as StoryIDs, G as GetItemInput, I as Item } from './connection-fC9QqgNx.js';
+import 'zod';
+
+/** Go zero value for ListStoryIDsInput in scripted cases. */
+declare const emptyListStoryIDsInput: ListStoryIDsInput;
+/** Go zero value for StoryIDs in scripted cases. */
+declare const emptyStoryIDs: StoryIDs;
+/** Go zero value for GetItemInput in scripted cases. */
+declare const emptyGetItemInput: GetItemInput;
+/** Go zero value for Item in scripted cases. */
+declare const emptyItem: Item;
+/** Script the listed branch. */
+declare function listStoryIDsListed(value: StoryIDs, failure?: Failure): Case<StoryIDs>;
+/** Script the providerRejected branch. */
+declare function listStoryIDsProviderRejected(value: StoryIDs, failure?: Failure): Case<StoryIDs>;
+/** Script the invalidResponse branch. */
+declare function listStoryIDsInvalidResponse(value: StoryIDs, failure?: Failure): Case<StoryIDs>;
+/** Script the defect branch. */
+declare function listStoryIDsDefect(value: StoryIDs, failure?: Failure): Case<StoryIDs>;
+/** Script a safe retry of listStoryIDs. */
+declare function listStoryIDsRetry(failure: Failure, retryAfterMs?: number): Case<StoryIDs>;
+/** Manifest scenario developerFeed for listStoryIDs. */
+declare function listStoryIDsDeveloperFeed(): Case<StoryIDs>;
+/** Default listStoryIDs scenario. */
+declare function listStoryIDsDefault(): Case<StoryIDs>;
+/** Manifest scenario feedRejected for listStoryIDs. */
+declare function listStoryIDsFeedRejected(): Case<StoryIDs>;
+/** Script the found branch. */
+declare function getItemFound(value: Item, failure?: Failure): Case<Item>;
+/** Script the notFound branch. */
+declare function getItemNotFound(value: Item, failure?: Failure): Case<Item>;
+/** Script the providerRejected branch. */
+declare function getItemProviderRejected(value: Item, failure?: Failure): Case<Item>;
+/** Script the invalidResponse branch. */
+declare function getItemInvalidResponse(value: Item, failure?: Failure): Case<Item>;
+/** Script the defect branch. */
+declare function getItemDefect(value: Item, failure?: Failure): Case<Item>;
+/** Script a safe retry of getItem. */
+declare function getItemRetry(failure: Failure, retryAfterMs?: number): Case<Item>;
+/** Manifest scenario compilerStory for getItem. */
+declare function getItemCompilerStory(): Case<Item>;
+/** Default getItem scenario. */
+declare function getItemDefault(): Case<Item>;
+/** Manifest scenario itemMissing for getItem. */
+declare function getItemItemMissing(): Case<Item>;
+/** Manifest scenario itemRejected for getItem. */
+declare function getItemItemRejected(): Case<Item>;
+/** Scripted operations and manifest defaults for this connector. */
+declare class GeneratedMock implements Operations {
+    #private;
+    constructor(connectionName: string);
+    connection(): Connection;
+    listStoryIDs(): MockQuery<ListStoryIDsInput, StoryIDs>;
+    getItem(): MockQuery<GetItemInput, Item>;
+    assertNoFailures(): void;
+}
+
+export { GeneratedMock, emptyGetItemInput, emptyItem, emptyListStoryIDsInput, emptyStoryIDs, getItemCompilerStory, getItemDefault, getItemDefect, getItemFound, getItemInvalidResponse, getItemItemMissing, getItemItemRejected, getItemNotFound, getItemProviderRejected, getItemRetry, listStoryIDsDefault, listStoryIDsDefect, listStoryIDsDeveloperFeed, listStoryIDsFeedRejected, listStoryIDsInvalidResponse, listStoryIDsListed, listStoryIDsProviderRejected, listStoryIDsRetry };

package/dist/hackernewsmock.js

@@ -0,0 +1,138 @@
+import {
+  ConnectorID,
+  GetItemDefinition,
+  GetItemInputSchema,
+  ItemSchema,
+  ListStoryIDsDefinition,
+  ListStoryIDsInputSchema,
+  ProviderID,
+  StoryIDsSchema,
+  newConnectionWithOperations
+} from "./chunk-23APJHSI.js";
+
+// src/generated/mock.ts
+import { branchCase, retryCase, newQuery } from "@superdurable/connectors-sdk/connectormock";
+var emptyListStoryIDsInput = ListStoryIDsInputSchema.parse({
+  "feed": "",
+  "limit": 0
+});
+var emptyStoryIDs = StoryIDsSchema.parse({
+  "ids": [],
+  "hasMore": false,
+  "observedAt": "0001-01-01T00:00:00Z"
+});
+var emptyGetItemInput = GetItemInputSchema.parse({
+  "id": 0
+});
+var emptyItem = ItemSchema.parse({
+  "id": 0,
+  "type": "",
+  "discussionUrl": ""
+});
+function listStoryIDsListed(value, failure) {
+  return branchCase("listed", value, failure);
+}
+function listStoryIDsProviderRejected(value, failure) {
+  return branchCase("providerRejected", value, failure);
+}
+function listStoryIDsInvalidResponse(value, failure) {
+  return branchCase("invalidResponse", value, failure);
+}
+function listStoryIDsDefect(value, failure) {
+  return branchCase("defect", value, failure);
+}
+function listStoryIDsRetry(failure, retryAfterMs = 0) {
+  return retryCase(failure, retryAfterMs);
+}
+function listStoryIDsDeveloperFeed() {
+  const value = StoryIDsSchema.parse({ "hasMore": true, "ids": [42001], "observedAt": "2026-10-26T12:00:00Z" });
+  return branchCase("listed", value);
+}
+function listStoryIDsDefault() {
+  return listStoryIDsDeveloperFeed();
+}
+function listStoryIDsFeedRejected() {
+  const value = emptyStoryIDs;
+  return branchCase("providerRejected", value, { kind: "PROVIDER_REJECTION", provider: ConnectorID, operation: "listStoryIDs", message: "Hacker News rejected the feed request." });
+}
+function getItemFound(value, failure) {
+  return branchCase("found", value, failure);
+}
+function getItemNotFound(value, failure) {
+  return branchCase("notFound", value, failure);
+}
+function getItemProviderRejected(value, failure) {
+  return branchCase("providerRejected", value, failure);
+}
+function getItemInvalidResponse(value, failure) {
+  return branchCase("invalidResponse", value, failure);
+}
+function getItemDefect(value, failure) {
+  return branchCase("defect", value, failure);
+}
+function getItemRetry(failure, retryAfterMs = 0) {
+  return retryCase(failure, retryAfterMs);
+}
+function getItemCompilerStory() {
+  const value = ItemSchema.parse({ "by": "compilerdev", "descendants": 0, "discussionUrl": "https://news.ycombinator.com/item?id=42001", "id": 42001, "score": 100, "time": 1793016e3, "title": "A compiler release", "type": "story", "url": "https://example.com/compiler" });
+  return branchCase("found", value);
+}
+function getItemDefault() {
+  return getItemCompilerStory();
+}
+function getItemItemMissing() {
+  const value = emptyItem;
+  return branchCase("notFound", value, { kind: "NOT_FOUND", provider: ConnectorID, operation: "getItem", message: "Hacker News item is deleted or dead." });
+}
+function getItemItemRejected() {
+  const value = emptyItem;
+  return branchCase("providerRejected", value, { kind: "PROVIDER_REJECTION", provider: ConnectorID, operation: "getItem", message: "Hacker News rejected the item request." });
+}
+var GeneratedMock = class {
+  #listStoryIDs;
+  #getItem;
+  #connection;
+  constructor(connectionName) {
+    this.#listStoryIDs = newQuery(ListStoryIDsDefinition).default(listStoryIDsDefault());
+    this.#getItem = newQuery(GetItemDefinition).default(getItemDefault());
+    this.#connection = newConnectionWithOperations(this, { provider: ProviderID, name: connectionName });
+  }
+  connection() {
+    return this.#connection;
+  }
+  listStoryIDs() {
+    return this.#listStoryIDs;
+  }
+  getItem() {
+    return this.#getItem;
+  }
+  assertNoFailures() {
+    this.#listStoryIDs.assertNoFailures();
+    this.#getItem.assertNoFailures();
+  }
+};
+export {
+  GeneratedMock,
+  emptyGetItemInput,
+  emptyItem,
+  emptyListStoryIDsInput,
+  emptyStoryIDs,
+  getItemCompilerStory,
+  getItemDefault,
+  getItemDefect,
+  getItemFound,
+  getItemInvalidResponse,
+  getItemItemMissing,
+  getItemItemRejected,
+  getItemNotFound,
+  getItemProviderRejected,
+  getItemRetry,
+  listStoryIDsDefault,
+  listStoryIDsDefect,
+  listStoryIDsDeveloperFeed,
+  listStoryIDsFeedRejected,
+  listStoryIDsInvalidResponse,
+  listStoryIDsListed,
+  listStoryIDsProviderRejected,
+  listStoryIDsRetry
+};

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import { G as GetItemInput, I as Item, a as Config, L as ListStoryIDsInput, S as StoryIDs, C as Connection, O as Operations } from './connection-fC9QqgNx.js';
+export { b as Credentials, c as GetItemInputSchema, d as ListStoryIDsInputSchema, n as newConnection, e as newConnectionWithOperations } from './connection-fC9QqgNx.js';
+import { LoadedProject } from '@superdurable/connectors-sdk/projectconfig';
+import * as _superdurable_connectors_sdk from '@superdurable/connectors-sdk';
+import { Query, Call, QueryAttempt, QueryStepConfig, QueryResult, QueryStep, QueryDefinition } from '@superdurable/connectors-sdk';
+import { ProviderRequest, ProviderResponse } from '@superdurable/connectors-sdk/providerhttp';
+import { StepTarget } from '@superdurable/dex';
+import 'zod';
+
+/** Injectable HTTP sender and clock for deterministic provider replay. */
+interface HackerNewsClientOptions {
+    /** Send one bounded request without redirect following. */
+    send?: (request: ProviderRequest) => Promise<ProviderResponse>;
+    /** Clock for observed feed time and Retry-After. */
+    now?: () => Date;
+}
+/** Public Hacker News API client bound to immutable configuration. */
+declare class HackerNewsClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxResponseBytes;
+    private readonly send;
+    readonly now: () => Date;
+    /** Validate configuration before making requests. */
+    constructor(config: Config, options?: HackerNewsClientOptions);
+    /** Bind the feed Query. */
+    listStoryIDs(): ListStoryIDsOperation;
+    /** Bind the item Query. */
+    getItem(): GetItemOperation;
+    /** Send one read and classify its HTTP or transport outcome. */
+    getJSON<Output>(call: Call, operation: string, path: string, zero: Output, decode: (body: Uint8Array) => QueryAttempt<Output>): Promise<QueryAttempt<Output>>;
+}
+/** Read a bounded feed snapshot. */
+declare class ListStoryIDsOperation implements Query<ListStoryIDsInput, StoryIDs> {
+    private readonly client;
+    /** Bind the owning client. */ constructor(client: HackerNewsClient);
+    /** Return manifest operation metadata. */ definition(): _superdurable_connectors_sdk.QueryDefinition;
+    /** Validate the feed and decode one provider response. */
+    invoke(call: Call, input: ListStoryIDsInput): Promise<QueryAttempt<StoryIDs>>;
+}
+/** Read one Hacker News story, comment, job, poll, or poll option. */
+declare class GetItemOperation implements Query<GetItemInput, Item> {
+    private readonly client;
+    /** Bind the owning client. */ constructor(client: HackerNewsClient);
+    /** Return manifest operation metadata. */ definition(): _superdurable_connectors_sdk.QueryDefinition;
+    /** Validate identity and decode one item response. */
+    invoke(call: Call, input: GetItemInput): Promise<QueryAttempt<Item>>;
+}
+
+/** Configuration for the listStoryIDs connector Step. */
+interface ListStoryIDsStepConfig<StepInput, OperationInput = ListStoryIDsInput, OperationOutput = StoryIDs> extends Omit<QueryStepConfig<StepInput, OperationInput, OperationOutput>, 'operation' | 'connection' | 'branches'> {
+    /** Named connection supplying this operation. */
+    connection: Connection<{
+        listStoryIDs(): Query<OperationInput, OperationOutput>;
+    }>;
+    /** Name matching the bound connection. */
+    connectionName: string;
+    /** The feed snapshot was read. */
+    listed: StepTarget<QueryResult<OperationOutput>>;
+    /** Hacker News rejected the request. */
+    providerRejected?: StepTarget<QueryResult<OperationOutput>>;
+    /** Hacker News returned malformed or oversized data. */
+    invalidResponse?: StepTarget<QueryResult<OperationOutput>>;
+    /** Local input or connection configuration is invalid. */
+    defect?: StepTarget<QueryResult<OperationOutput>>;
+}
+/** Build the listStoryIDs Step from a named connection. */
+declare function newListStoryIDsStep<StepInput, OperationInput = ListStoryIDsInput, OperationOutput = StoryIDs>(configuration: ListStoryIDsStepConfig<StepInput, OperationInput, OperationOutput>): QueryStep<StepInput, OperationInput, OperationOutput>;
+/** Configuration for the getItem connector Step. */
+interface GetItemStepConfig<StepInput, OperationInput = GetItemInput, OperationOutput = Item> extends Omit<QueryStepConfig<StepInput, OperationInput, OperationOutput>, 'operation' | 'connection' | 'branches'> {
+    /** Named connection supplying this operation. */
+    connection: Connection<{
+        getItem(): Query<OperationInput, OperationOutput>;
+    }>;
+    /** Name matching the bound connection. */
+    connectionName: string;
+    /** The public item was read. */
+    found: StepTarget<QueryResult<OperationOutput>>;
+    /** The item is missing, deleted, or dead. */
+    notFound?: StepTarget<QueryResult<OperationOutput>>;
+    /** Hacker News rejected the request. */
+    providerRejected?: StepTarget<QueryResult<OperationOutput>>;
+    /** Hacker News returned malformed or oversized data. */
+    invalidResponse?: StepTarget<QueryResult<OperationOutput>>;
+    /** Local input or connection configuration is invalid. */
+    defect?: StepTarget<QueryResult<OperationOutput>>;
+}
+/** Build the getItem Step from a named connection. */
+declare function newGetItemStep<StepInput, OperationInput = GetItemInput, OperationOutput = Item>(configuration: GetItemStepConfig<StepInput, OperationInput, OperationOutput>): QueryStep<StepInput, OperationInput, OperationOutput>;
+
+/** Stable connector identity. */
+declare const ConnectorID = "hacker-news-daily";
+/** Provider identity for named connections. */
+declare const ProviderID = "hacker-news";
+/** Branch IDs for listStoryIDs. */
+declare const ListStoryIDsBranch: {
+    readonly Listed: "listed";
+    readonly ProviderRejected: "providerRejected";
+    readonly InvalidResponse: "invalidResponse";
+    readonly Defect: "defect";
+};
+/** The feed snapshot was read. */
+declare const ListStoryIDsBranchListed: "listed";
+/** Hacker News rejected the request. */
+declare const ListStoryIDsBranchProviderRejected: "providerRejected";
+/** Hacker News returned malformed or oversized data. */
+declare const ListStoryIDsBranchInvalidResponse: "invalidResponse";
+/** Local input or connection configuration is invalid. */
+declare const ListStoryIDsBranchDefect: "defect";
+/** Manifest definition for listStoryIDs. */
+declare const ListStoryIDsDefinition: QueryDefinition;
+/** Manifest metadata for listStoryIDs. */
+declare const ListStoryIDsMetadata: {
+    readonly kind: "query";
+    readonly idempotency: "none";
+    readonly authorization: "none";
+};
+/** Branch IDs for getItem. */
+declare const GetItemBranch: {
+    readonly Found: "found";
+    readonly NotFound: "notFound";
+    readonly ProviderRejected: "providerRejected";
+    readonly InvalidResponse: "invalidResponse";
+    readonly Defect: "defect";
+};
+/** The public item was read. */
+declare const GetItemBranchFound: "found";
+/** The item is missing, deleted, or dead. */
+declare const GetItemBranchNotFound: "notFound";
+/** Hacker News rejected the request. */
+declare const GetItemBranchProviderRejected: "providerRejected";
+/** Hacker News returned malformed or oversized data. */
+declare const GetItemBranchInvalidResponse: "invalidResponse";
+/** Local input or connection configuration is invalid. */
+declare const GetItemBranchDefect: "defect";
+/** Manifest definition for getItem. */
+declare const GetItemDefinition: QueryDefinition;
+/** Manifest metadata for getItem. */
+declare const GetItemMetadata: {
+    readonly kind: "query";
+    readonly idempotency: "none";
+    readonly authorization: "none";
+};
+
+/** Bind the named public connection and honor all project configuration fields. */
+declare function newProjectConnection(project: LoadedProject, connectionName: string): Connection<Operations>;
+
+export { Config, Connection, ConnectorID, GetItemBranch, GetItemBranchDefect, GetItemBranchFound, GetItemBranchInvalidResponse, GetItemBranchNotFound, GetItemBranchProviderRejected, GetItemDefinition, GetItemInput, GetItemMetadata, GetItemOperation, HackerNewsClient, type HackerNewsClientOptions, Item, ListStoryIDsBranch, ListStoryIDsBranchDefect, ListStoryIDsBranchInvalidResponse, ListStoryIDsBranchListed, ListStoryIDsBranchProviderRejected, ListStoryIDsDefinition, ListStoryIDsInput, ListStoryIDsMetadata, ListStoryIDsOperation, ProviderID, StoryIDs, newGetItemStep, newListStoryIDsStep, newProjectConnection };

package/dist/index.js

@@ -0,0 +1,300 @@
+import {
+  Connection,
+  ConnectorID,
+  GetItemBranch,
+  GetItemBranchDefect,
+  GetItemBranchFound,
+  GetItemBranchInvalidResponse,
+  GetItemBranchNotFound,
+  GetItemBranchProviderRejected,
+  GetItemDefinition,
+  GetItemInputSchema,
+  GetItemMetadata,
+  ListStoryIDsBranch,
+  ListStoryIDsBranchDefect,
+  ListStoryIDsBranchInvalidResponse,
+  ListStoryIDsBranchListed,
+  ListStoryIDsBranchProviderRejected,
+  ListStoryIDsDefinition,
+  ListStoryIDsInputSchema,
+  ListStoryIDsMetadata,
+  ProviderID,
+  newConnection,
+  newConnectionWithOperations,
+  newProjectConnection
+} from "./chunk-23APJHSI.js";
+
+// src/index.ts
+import { z } from "zod";
+
+// src/client.ts
+import { newQueryBranch, newQueryRetry } from "@superdurable/connectors-sdk";
+import { BodyTooLargeError, ProviderStalledError, ProviderTransportError, parseRetryAfter, sendProviderRequest, validateBaseURL } from "@superdurable/connectors-sdk/providerhttp";
+var defaultBaseUrl = "https://hacker-news.firebaseio.com/v0";
+var zeroTime = "0001-01-01T00:00:00Z";
+var zeroIds = { ids: [], hasMore: false, observedAt: zeroTime };
+var zeroItem = { id: 0, type: "", discussionUrl: "" };
+var validFeeds = /* @__PURE__ */ new Set(["top", "best", "new", "ask", "show"]);
+var validItemTypes = /* @__PURE__ */ new Set(["story", "comment", "job", "poll", "pollopt"]);
+var HackerNewsClient = class {
+  baseUrl;
+  timeoutMs;
+  maxResponseBytes;
+  send;
+  now;
+  /** Validate configuration before making requests. */
+  constructor(config, options = {}) {
+    if (!config) throw new TypeError("Hacker News configuration is required");
+    this.baseUrl = validateBaseURL(config.baseUrl || defaultBaseUrl);
+    this.timeoutMs = config.timeoutMs === void 0 || config.timeoutMs === 0 ? 15e3 : config.timeoutMs;
+    this.maxResponseBytes = config.maxResponseBytes === void 0 || config.maxResponseBytes === 0 ? 1048576 : config.maxResponseBytes;
+    if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0 || !Number.isSafeInteger(this.maxResponseBytes) || this.maxResponseBytes <= 0) {
+      throw new TypeError("Hacker News timeout and maxResponseBytes must be positive");
+    }
+    this.send = options.send ?? sendProviderRequest;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  /** Bind the feed Query. */
+  listStoryIDs() {
+    return new ListStoryIDsOperation(this);
+  }
+  /** Bind the item Query. */
+  getItem() {
+    return new GetItemOperation(this);
+  }
+  /** Send one read and classify its HTTP or transport outcome. */
+  async getJSON(call, operation, path, zero, decode) {
+    let response;
+    try {
+      response = await this.send({
+        url: this.baseUrl + path,
+        method: "GET",
+        headers: { Accept: "application/json", "User-Agent": "superdurable-hacker-news-daily/0.1" },
+        maxResponseBytes: this.maxResponseBytes,
+        addressPolicy: this.baseUrl === defaultBaseUrl ? "publicHTTPS" : "privateNetworkHTTP",
+        timeoutMs: this.timeoutMs,
+        signal: call.context.cancellationSignal
+      });
+    } catch (error) {
+      if (error instanceof BodyTooLargeError) {
+        const status2 = error.status ?? 0;
+        if (status2 === 408 || status2 === 429 || status2 >= 500) {
+          const retryAfter = error.headers?.["retry-after"];
+          return newQueryRetry(failure(operation, status2 === 429 ? "RATE_LIMIT" : "AVAILABILITY", "Hacker News is temporarily unavailable"), parseRetryAfter(Array.isArray(retryAfter) ? retryAfter[0] ?? "" : retryAfter ?? "", this.now()));
+        }
+        if (status2 === 404 && operation === "getItem") return failed(operation, "notFound", zero, "NOT_FOUND", "Hacker News resource was not found");
+        if (status2 !== 200) return failed(operation, "providerRejected", zero, "PROVIDER_REJECTION", "Hacker News rejected the request");
+        return failed(operation, "invalidResponse", zero, "RESPONSE_TOO_LARGE", "Hacker News response exceeded the configured limit");
+      }
+      const isInterruptedResponse = (error instanceof ProviderTransportError || error instanceof ProviderStalledError) && error.status === 200;
+      return newQueryRetry(failure(operation, "AVAILABILITY", isInterruptedResponse ? "Hacker News response was interrupted" : "Hacker News request failed"), 0);
+    }
+    const status = response.status;
+    if (status === 408 || status === 429 || status >= 500) {
+      const retryAfter = response.headers["retry-after"];
+      return newQueryRetry(failure(operation, status === 429 ? "RATE_LIMIT" : "AVAILABILITY", "Hacker News is temporarily unavailable"), parseRetryAfter(Array.isArray(retryAfter) ? retryAfter[0] ?? "" : retryAfter ?? "", this.now()));
+    }
+    if (status === 404 && operation === "getItem") return failed(operation, "notFound", zero, "NOT_FOUND", "Hacker News resource was not found");
+    if (status !== 200) return failed(operation, "providerRejected", zero, "PROVIDER_REJECTION", "Hacker News rejected the request");
+    return decode(response.body);
+  }
+};
+var ListStoryIDsOperation = class {
+  /** Bind the owning client. */
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Return manifest operation metadata. */
+  definition() {
+    return ListStoryIDsDefinition;
+  }
+  /** Validate the feed and decode one provider response. */
+  invoke(call, input) {
+    const feed = input.feed || "top";
+    const limit = input.limit || 50;
+    if (!validFeeds.has(feed)) return Promise.resolve(failed("listStoryIDs", "defect", zeroIds, "VALIDATION", "feed must be top, best, new, ask, or show"));
+    if (!Number.isInteger(limit) || limit < 1 || limit > 500) return Promise.resolve(failed("listStoryIDs", "defect", zeroIds, "VALIDATION", "limit must be from 1 through 500"));
+    return this.client.getJSON(call, "listStoryIDs", `/${feed}stories.json`, zeroIds, (body) => {
+      let ids;
+      try {
+        ids = parseProviderJSON(body);
+      } catch {
+        ids = void 0;
+      }
+      if (!Array.isArray(ids)) return failed("listStoryIDs", "invalidResponse", zeroIds, "PROTOCOL", "Hacker News returned an invalid feed");
+      const feedIDs = [];
+      for (const id of ids) {
+        if (id === null) return failed("listStoryIDs", "invalidResponse", zeroIds, "PROTOCOL", "Hacker News returned an invalid item ID");
+        try {
+          feedIDs.push(strictInteger(id, "item ID"));
+        } catch (error) {
+          return failed("listStoryIDs", "invalidResponse", zeroIds, "PROTOCOL", `Hacker News returned an invalid feed: ${fieldError(error)}`);
+        }
+      }
+      if (feedIDs.some((id) => id <= 0)) return failed("listStoryIDs", "invalidResponse", zeroIds, "PROTOCOL", "Hacker News returned an invalid item ID");
+      return newQueryBranch("listed", { ids: feedIDs.slice(0, limit), hasMore: feedIDs.length > limit, observedAt: goTimestamp(this.client.now()) }, {});
+    });
+  }
+};
+var GetItemOperation = class {
+  /** Bind the owning client. */
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Return manifest operation metadata. */
+  definition() {
+    return GetItemDefinition;
+  }
+  /** Validate identity and decode one item response. */
+  invoke(call, input) {
+    if (!Number.isSafeInteger(input.id) || input.id <= 0) return Promise.resolve(failed("getItem", "defect", zeroItem, "VALIDATION", "item ID must be positive"));
+    return this.client.getJSON(call, "getItem", `/item/${input.id}.json`, zeroItem, (body) => {
+      let value;
+      try {
+        value = parseProviderJSON(body);
+      } catch {
+        return failed("getItem", "invalidResponse", zeroItem, "PROTOCOL", "Hacker News returned malformed item JSON");
+      }
+      if (value === null) return failed("getItem", "notFound", zeroItem, "NOT_FOUND", "Hacker News item is deleted or dead");
+      let item;
+      try {
+        item = decodeItem(value);
+      } catch (error) {
+        return failed("getItem", "invalidResponse", zeroItem, "PROTOCOL", `Hacker News returned malformed item JSON: ${fieldError(error)}`);
+      }
+      if (item.deleted || item.dead) return failed("getItem", "notFound", zeroItem, "NOT_FOUND", "Hacker News item is deleted or dead");
+      if (item.id !== input.id) return failed("getItem", "invalidResponse", zeroItem, "PROTOCOL", "Hacker News returned a different item ID");
+      if (!validItemTypes.has(item.type)) return failed("getItem", "invalidResponse", zeroItem, "PROTOCOL", "Hacker News returned an unknown item type");
+      if (item.kids?.some((id) => id <= 0)) return failed("getItem", "invalidResponse", zeroItem, "PROTOCOL", "Hacker News returned an invalid child ID");
+      return newQueryBranch("found", item, {});
+    });
+  }
+};
+function decodeItem(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("item must be an object");
+  const document = value;
+  const string = (name) => {
+    const field = document[name];
+    if (field === void 0 || field === null) return "";
+    if (typeof field !== "string") throw new TypeError(name);
+    return field;
+  };
+  const integer = (name) => {
+    const field = document[name];
+    if (field === void 0 || field === null) return 0;
+    return strictInteger(field, name);
+  };
+  const boolean = (name) => {
+    const field = document[name];
+    if (field === void 0 || field === null) return false;
+    if (typeof field !== "boolean") throw new TypeError(name);
+    return field;
+  };
+  const kids = document.kids;
+  if (kids !== void 0 && kids !== null && !Array.isArray(kids)) throw new TypeError("kids");
+  const childIDs = Array.isArray(kids) ? kids.map((id2) => id2 === null ? 0 : strictInteger(id2, "kids")) : [];
+  const id = integer("id");
+  const item = { id, type: string("type"), discussionUrl: `https://news.ycombinator.com/item?id=${id}` };
+  for (const name of ["by", "title", "text", "url"]) {
+    const field = string(name);
+    if (field) item[name] = field;
+  }
+  for (const name of ["time", "score", "descendants", "parent"]) {
+    const field = integer(name);
+    if (field) item[name] = field;
+  }
+  if (childIDs.length) item.kids = childIDs;
+  if (boolean("deleted")) item.deleted = true;
+  if (boolean("dead")) item.dead = true;
+  return item;
+}
+function parseProviderJSON(body) {
+  const exactJSON = JSON;
+  return exactJSON.parse(Buffer.from(body).toString("utf8"), (_key, value, context) => typeof value === "number" && context?.source ? exactJSON.rawJSON(context.source) : value);
+}
+function strictInteger(value, name) {
+  const source = value && typeof value === "object" && "rawJSON" in value ? String(value.rawJSON) : "";
+  if (!/^-?(?:0|[1-9]\d*)$/.test(source)) throw new TypeError(name);
+  const integer = Number(source);
+  if (!Number.isSafeInteger(integer)) throw new TypeError(name);
+  return integer;
+}
+function fieldError(error) {
+  return error instanceof Error ? error.message : "unknown field";
+}
+function goTimestamp(time) {
+  return time.toISOString().replace(/\.000Z$/, "Z").replace(/(\.\d*?[1-9])0+Z$/, "$1Z");
+}
+function failure(operation, kind, message) {
+  return { kind, provider: "hacker-news", operation, message };
+}
+function failed(operation, branch, zero, kind, message) {
+  return newQueryBranch(branch, zero, {}, failure(operation, kind, message));
+}
+
+// src/generated/steps.ts
+import { goToBranch, newQueryStep } from "@superdurable/connectors-sdk";
+function newListStoryIDsStep(configuration) {
+  const { connection, connectionName, listed, providerRejected, invalidResponse, defect, ...stepConfiguration } = configuration;
+  if (!connection || connection.reference.name !== connectionName) throw new TypeError("Step connection name differs from the bound connection");
+  return newQueryStep({ ...stepConfiguration, operation: connection.operations.listStoryIDs(), connection: connection.reference, branches: [
+    goToBranch("listed", listed),
+    ...providerRejected ? [goToBranch("providerRejected", providerRejected)] : [],
+    ...invalidResponse ? [goToBranch("invalidResponse", invalidResponse)] : [],
+    ...defect ? [goToBranch("defect", defect)] : []
+  ] });
+}
+function newGetItemStep(configuration) {
+  const { connection, connectionName, found, notFound, providerRejected, invalidResponse, defect, ...stepConfiguration } = configuration;
+  if (!connection || connection.reference.name !== connectionName) throw new TypeError("Step connection name differs from the bound connection");
+  return newQueryStep({ ...stepConfiguration, operation: connection.operations.getItem(), connection: connection.reference, branches: [
+    goToBranch("found", found),
+    ...notFound ? [goToBranch("notFound", notFound)] : [],
+    ...providerRejected ? [goToBranch("providerRejected", providerRejected)] : [],
+    ...invalidResponse ? [goToBranch("invalidResponse", invalidResponse)] : [],
+    ...defect ? [goToBranch("defect", defect)] : []
+  ] });
+}
+
+// src/index.ts
+function newProjectConnection2(project, connectionName) {
+  return newProjectConnection(project, connectionName, (loadedProject, name) => {
+    const selected = loadedProject.configuration.connections.find((entry) => entry.connectorId === "hacker-news-daily" && entry.connectionName === name);
+    if (!selected) throw new TypeError("Hacker News project connection is not configured");
+    const raw = z.strictObject({ baseUrl: z.string().optional(), timeout: z.number().int().refine(Number.isSafeInteger).optional(), maxResponseBytes: z.number().int().refine(Number.isSafeInteger).optional() }).parse(selected.configuration);
+    const config = { baseUrl: raw.baseUrl, timeoutMs: raw.timeout === void 0 ? void 0 : raw.timeout / 1e6, maxResponseBytes: raw.maxResponseBytes };
+    return new HackerNewsClient(config);
+  });
+}
+export {
+  Connection,
+  ConnectorID,
+  GetItemBranch,
+  GetItemBranchDefect,
+  GetItemBranchFound,
+  GetItemBranchInvalidResponse,
+  GetItemBranchNotFound,
+  GetItemBranchProviderRejected,
+  GetItemDefinition,
+  GetItemInputSchema,
+  GetItemMetadata,
+  GetItemOperation,
+  HackerNewsClient,
+  ListStoryIDsBranch,
+  ListStoryIDsBranchDefect,
+  ListStoryIDsBranchInvalidResponse,
+  ListStoryIDsBranchListed,
+  ListStoryIDsBranchProviderRejected,
+  ListStoryIDsDefinition,
+  ListStoryIDsInputSchema,
+  ListStoryIDsMetadata,
+  ListStoryIDsOperation,
+  ProviderID,
+  newConnection,
+  newConnectionWithOperations,
+  newGetItemStep,
+  newListStoryIDsStep,
+  newProjectConnection2 as newProjectConnection
+};

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@superdurable/connector-hackernews",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "Hacker News connector for Dex TypeScript applications",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superdurable/dex-connectors-library.git",
+    "directory": "connectors/hackernews/typescript"
+  },
+  "type": "module",
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./hackernewsmock": {
+      "types": "./dist/hackernewsmock.d.ts",
+      "import": "./dist/hackernewsmock.js"
+    },
+    "./dex-connector.json": "./dex-connector.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "dex-connector.json"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsup src/index.ts src/hackernewsmock.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test examples",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run lint && npm test && npm run build",
+    "example:top-story": "tsx examples/top-story/worker.ts",
+    "integration:top-story": "tsx examples/top-story/integration.ts"
+  },
+  "dependencies": {
+    "@superdurable/connectors-sdk": "0.8.0",
+    "@superdurable/dex": ">=1.28.0",
+    "zod": "^4.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0",
+    "yaml": "^2.9.1"
+  }
+}