@squadbase/vite-server 0.1.17-dev.a9ddcfa → 0.1.17-dev.d4fff69

package/dist/connectors/hackernews.js

@@ -0,0 +1,890 @@
+// ../connectors/src/connectors/hackernews/sdk/index.ts
+var FIREBASE_BASE_URL = "https://hacker-news.firebaseio.com/v0";
+var ALGOLIA_BASE_URL = "https://hn.algolia.com/api/v1";
+function createClient(_params) {
+  function buildUrl(base, path2, query) {
+    if (/^https?:\/\//i.test(path2)) {
+      throw new Error("hackernews: absolute URLs are not allowed");
+    }
+    const url = new URL(`${base}${path2.startsWith("/") ? "" : "/"}${path2}`);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    return url.toString();
+  }
+  async function parseJson(res) {
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : null;
+    if (!res.ok) {
+      throw new Error(`hackernews: ${res.status} ${res.statusText}: ${text}`);
+    }
+    return data;
+  }
+  async function requestFirebase(path2) {
+    return fetch(buildUrl(FIREBASE_BASE_URL, path2), {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    });
+  }
+  async function requestAlgolia(path2, options) {
+    return fetch(buildUrl(ALGOLIA_BASE_URL, path2, options?.query), {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    });
+  }
+  async function getStoryIds(kind, options) {
+    const pathByKind = {
+      top: "/topstories.json",
+      new: "/newstories.json",
+      best: "/beststories.json",
+      ask: "/askstories.json",
+      show: "/showstories.json",
+      job: "/jobstories.json"
+    };
+    const ids = await parseJson(
+      await requestFirebase(pathByKind[kind])
+    );
+    return ids.slice(0, options?.limit ?? ids.length);
+  }
+  async function getItem(id) {
+    return parseJson(
+      await requestFirebase(`/item/${id}.json`)
+    );
+  }
+  return {
+    requestFirebase,
+    requestAlgolia,
+    getItem,
+    async getUser(username) {
+      return parseJson(
+        await requestFirebase(`/user/${encodeURIComponent(username)}.json`)
+      );
+    },
+    async getMaxItem() {
+      return parseJson(await requestFirebase("/maxitem.json"));
+    },
+    async getUpdates() {
+      return parseJson(
+        await requestFirebase("/updates.json")
+      );
+    },
+    getStoryIds,
+    async getItems(ids, options) {
+      const limit = options?.limit ?? ids.length;
+      const concurrency = Math.max(1, Math.min(options?.concurrency ?? 5, 10));
+      const targetIds = ids.slice(0, limit);
+      const results = [];
+      for (let i = 0; i < targetIds.length; i += concurrency) {
+        const batch = targetIds.slice(i, i + concurrency);
+        const items = await Promise.all(batch.map((id) => getItem(id)));
+        for (const item of items) {
+          if (item) results.push(item);
+        }
+      }
+      return results;
+    },
+    async search(query, options) {
+      const path2 = options?.byDate ? "/search_by_date" : "/search";
+      return parseJson(
+        await requestAlgolia(path2, {
+          query: { query, hitsPerPage: 20, ...options?.query ?? {} }
+        })
+      );
+    }
+  };
+}
+
+// ../connectors/src/connector-onboarding.ts
+var ConnectorOnboarding = class {
+  /** Phase 1: Connection setup instructions (optional — some connectors don't need this) */
+  connectionSetupInstructions;
+  /** Phase 2: Data overview instructions */
+  dataOverviewInstructions;
+  constructor(config) {
+    this.connectionSetupInstructions = config.connectionSetupInstructions;
+    this.dataOverviewInstructions = config.dataOverviewInstructions;
+  }
+  getConnectionSetupPrompt(language) {
+    return this.connectionSetupInstructions?.[language] ?? null;
+  }
+  getDataOverviewInstructions(language) {
+    return this.dataOverviewInstructions[language];
+  }
+};
+
+// ../connectors/src/connector-tool.ts
+var ConnectorTool = class {
+  name;
+  description;
+  inputSchema;
+  outputSchema;
+  _execute;
+  constructor(config) {
+    this.name = config.name;
+    this.description = config.description;
+    this.inputSchema = config.inputSchema;
+    this.outputSchema = config.outputSchema;
+    this._execute = config.execute;
+  }
+  createTool(connections, config) {
+    return {
+      description: this.description,
+      inputSchema: this.inputSchema,
+      outputSchema: this.outputSchema,
+      execute: (input) => this._execute(input, connections, config)
+    };
+  }
+};
+
+// ../connectors/src/connector-plugin.ts
+var ConnectorPlugin = class _ConnectorPlugin {
+  slug;
+  authType;
+  name;
+  description;
+  iconUrl;
+  parameters;
+  releaseFlag;
+  proxyPolicy;
+  experimentalAttributes;
+  categories;
+  onboarding;
+  systemPrompt;
+  tools;
+  query;
+  checkConnection;
+  /**
+   * SQPD-1212: Logic-based, rule-driven connection setup. Connectors that
+   * implement this expose a step-by-step exploration flow (database/schema/
+   * table/etc. discovery) that the dashboard backend drives via the
+   * `/connections/:connectionId/setup` endpoint. Implement by delegating to
+   * `runSetupFlow` from `setup-flow.ts`.
+   */
+  setup;
+  /**
+   * Opt-out of the default "verify before save" behavior on connection
+   * creation. The backend invokes `checkConnection` synchronously while
+   * creating the connection and aborts (no row inserted) if it fails — this
+   * flag disables that for connectors where the check cannot succeed pre-save:
+   *
+   *   - `squadbase-db` populates `connection-url` only after Neon provisioning
+   *   - OAuth connectors require an OAuth-aware proxyFetch keyed by the
+   *     connectionId, which doesn't exist until the row is saved
+   *
+   * Exceptions are the explicit position; new credential-input connectors get
+   * the default verify-on-create behavior without opt-in.
+   */
+  skipConnectionCheckOnCreate;
+  constructor(config) {
+    this.slug = config.slug;
+    this.authType = config.authType;
+    this.name = config.name;
+    this.description = config.description;
+    this.iconUrl = config.iconUrl;
+    this.parameters = config.parameters;
+    this.releaseFlag = config.releaseFlag;
+    this.proxyPolicy = config.proxyPolicy;
+    this.experimentalAttributes = config.experimentalAttributes;
+    this.categories = config.categories ?? [];
+    this.onboarding = config.onboarding;
+    this.systemPrompt = config.systemPrompt;
+    this.tools = config.tools;
+    this.query = config.query;
+    this.checkConnection = config.checkConnection;
+    this.setup = config.setup;
+    this.skipConnectionCheckOnCreate = config.skipConnectionCheckOnCreate;
+  }
+  get connectorKey() {
+    return _ConnectorPlugin.deriveKey(this.slug, this.authType);
+  }
+  /**
+   * Create tools for connections that belong to this connector.
+   * Filters connections by connectorKey internally.
+   * Returns tools keyed as `connector_${connectorKey}_${toolName}`.
+   */
+  createTools(connections, config, opts) {
+    const myConnections = connections.filter(
+      (c) => _ConnectorPlugin.deriveKey(c.connector.slug, c.connector.authType) === this.connectorKey
+    );
+    const result = {};
+    for (const t of Object.values(this.tools)) {
+      const tool = t.createTool(myConnections, config);
+      const originalToModelOutput = tool.toModelOutput;
+      result[`connector_${this.connectorKey}_${t.name}`] = {
+        ...tool,
+        toModelOutput: async (options) => {
+          if (!originalToModelOutput) {
+            return opts.truncateOutput(options.output);
+          }
+          const modelOutput = await originalToModelOutput(options);
+          if (modelOutput.type === "text" || modelOutput.type === "json") {
+            return opts.truncateOutput(modelOutput.value);
+          }
+          return modelOutput;
+        }
+      };
+    }
+    return result;
+  }
+  static deriveKey(slug, authType) {
+    if (authType) return `${slug}-${authType}`;
+    const LEGACY_NULL_AUTH_TYPE_MAP = {
+      // user-password
+      "postgresql": "user-password",
+      "mysql": "user-password",
+      "clickhouse": "user-password",
+      "kintone": "user-password",
+      "squadbase-db": "user-password",
+      // service-account
+      "snowflake": "service-account",
+      "bigquery": "service-account",
+      "google-analytics": "service-account",
+      "google-calendar": "service-account",
+      "aws-athena": "service-account",
+      "redshift": "service-account",
+      // api-key
+      "databricks": "api-key",
+      "dbt": "api-key",
+      "airtable": "api-key",
+      "openai": "api-key",
+      "gemini": "api-key",
+      "anthropic": "api-key",
+      "wix-store": "api-key"
+    };
+    const fallbackAuthType = LEGACY_NULL_AUTH_TYPE_MAP[slug];
+    if (fallbackAuthType) return `${slug}-${fallbackAuthType}`;
+    return slug;
+  }
+};
+
+// ../connectors/src/setup-flow.ts
+async function runSetupFlow(flow, params, ctx, config) {
+  const runtime = {
+    params,
+    language: ctx.language,
+    config
+  };
+  let state = flow.initialState();
+  let answerIdx = 0;
+  const pendingParameterUpdates = [];
+  for (const step of flow.steps) {
+    const ans = ctx.answers[answerIdx];
+    if (ans && ans.questionSlug === step.slug) {
+      state = step.applyAnswer(state, ans.answer);
+      if (step.toParameterUpdates) {
+        pendingParameterUpdates.push(...step.toParameterUpdates(state));
+      }
+      answerIdx += 1;
+      continue;
+    }
+    const resolvedAllowFreeText = step.allowFreeText !== void 0 ? step.allowFreeText : true;
+    if (step.type === "text") {
+      if (step.fetchOptions) {
+        const options2 = await step.fetchOptions(state, runtime);
+        if (options2.length === 0) {
+          continue;
+        }
+      }
+      return {
+        type: "nextQuestion",
+        questionSlug: step.slug,
+        question: step.question[ctx.language],
+        questionType: "text",
+        allowFreeText: resolvedAllowFreeText,
+        ...pendingParameterUpdates.length > 0 && {
+          parameterUpdates: pendingParameterUpdates
+        }
+      };
+    }
+    const options = step.fetchOptions ? await step.fetchOptions(state, runtime) : [];
+    if (options.length === 0) {
+      continue;
+    }
+    return {
+      type: "nextQuestion",
+      questionSlug: step.slug,
+      question: step.question[ctx.language],
+      questionType: step.type,
+      options,
+      allowFreeText: resolvedAllowFreeText,
+      ...pendingParameterUpdates.length > 0 && {
+        parameterUpdates: pendingParameterUpdates
+      }
+    };
+  }
+  const dataInvestigationResult = await flow.finalize(state, runtime);
+  return {
+    type: "fulfilled",
+    dataInvestigationResult,
+    ...pendingParameterUpdates.length > 0 && {
+      parameterUpdates: pendingParameterUpdates
+    }
+  };
+}
+
+// ../connectors/src/auth-types.ts
+var AUTH_TYPES = {
+  OAUTH: "oauth",
+  API_KEY: "api-key",
+  JWT: "jwt",
+  SERVICE_ACCOUNT: "service-account",
+  PAT: "pat",
+  USER_PASSWORD: "user-password"
+};
+
+// ../connectors/src/connectors/hackernews/setup.ts
+var hackerNewsOnboarding = new ConnectorOnboarding({
+  dataOverviewInstructions: {
+    en: `1. Use connector_hackernews-api-key_requestFirebase with GET /topstories.json to inspect current top story ids
+2. Fetch a small sample of items with GET /item/{id}.json to understand story fields such as title, url, score, descendants, by, and time
+3. Use connector_hackernews-api-key_searchAlgolia only when keyword or historical search is required
+4. Prefer Firebase list endpoints for dashboards that show top, new, best, Ask HN, Show HN, or job stories`,
+    ja: `1. connector_hackernews-api-key_requestFirebase \u3067 GET /topstories.json \u3092\u547C\u3073\u51FA\u3057\u3001\u73FE\u5728\u306E\u30C8\u30C3\u30D7\u30B9\u30C8\u30FC\u30EA\u30FCID\u3092\u78BA\u8A8D\u3057\u307E\u3059
+2. GET /item/{id}.json \u3067\u5C11\u91CF\u306E item \u3092\u53D6\u5F97\u3057\u3001title, url, score, descendants, by, time \u306A\u3069\u306E\u30D5\u30A3\u30FC\u30EB\u30C9\u3092\u628A\u63E1\u3057\u307E\u3059
+3. \u30AD\u30FC\u30EF\u30FC\u30C9\u691C\u7D22\u3084\u5C65\u6B74\u691C\u7D22\u304C\u5FC5\u8981\u306A\u5834\u5408\u306E\u307F connector_hackernews-api-key_searchAlgolia \u3092\u4F7F\u7528\u3057\u307E\u3059
+4. top, new, best, Ask HN, Show HN, job stories \u306E\u30C0\u30C3\u30B7\u30E5\u30DC\u30FC\u30C9\u3067\u306F Firebase \u306E\u30EA\u30B9\u30C8\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3092\u512A\u5148\u3057\u307E\u3059`
+  }
+});
+
+// ../connectors/src/connectors/hackernews/setup-flow.ts
+var hackerNewsSetupFlow = {
+  initialState: () => ({}),
+  steps: [],
+  async finalize(_state, rt) {
+    const sections = rt.language === "ja" ? [
+      "## Hacker News",
+      "",
+      "- \u8A8D\u8A3C\u60C5\u5831\u306E\u5165\u529B\u306F\u4E0D\u8981\u3067\u3059\u3002",
+      "- \u901A\u5E38\u306E\u30E9\u30F3\u30AD\u30F3\u30B0\u3001item\u3001user\u3001updates \u306E\u53D6\u5F97\u306B\u306F\u516C\u5F0F Firebase API \u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+      "- Algolia API \u306F\u30AD\u30FC\u30EF\u30FC\u30C9\u691C\u7D22\u3084\u671F\u9593\u691C\u7D22\u304C\u5FC5\u8981\u306A\u6642\u3060\u3051\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+      "- \u30C0\u30C3\u30B7\u30E5\u30DC\u30FC\u30C9\u5B9F\u88C5\u3067\u306F\u3001item \u8A73\u7D30\u53D6\u5F97\u306E\u4E26\u5217\u6570\u3068\u4EF6\u6570\u3092\u6291\u3048\u3066\u304F\u3060\u3055\u3044\u3002"
+    ] : [
+      "## Hacker News",
+      "",
+      "- No credential input is required.",
+      "- Use the official Firebase API for rankings, items, users, and updates.",
+      "- Use the Algolia API only when keyword or date-range search is required.",
+      "- When building dashboards, keep item-detail fetch concurrency and result counts bounded."
+    ];
+    return sections.join("\n");
+  }
+};
+
+// ../connectors/src/connectors/hackernews/tools/request-firebase.ts
+import { z } from "zod";
+var BASE_URL = "https://hacker-news.firebaseio.com/v0";
+var REQUEST_TIMEOUT_MS = 6e4;
+var inputSchema = z.object({
+  toolUseIntent: z.string().optional().describe(
+    "Brief description of what you intend to accomplish with this tool call"
+  ),
+  connectionId: z.string().describe(
+    "ID of the Hacker News connection to use. This connector has no credentials, but the connection ID identifies the selected data source."
+  ),
+  path: z.string().describe(
+    "Firebase API path appended to https://hacker-news.firebaseio.com/v0. Examples: '/topstories.json', '/newstories.json', '/beststories.json', '/askstories.json', '/showstories.json', '/jobstories.json', '/item/8863.json', '/user/jl.json', '/maxitem.json', '/updates.json'."
+  ),
+  printPretty: z.boolean().optional().describe("Set true to append print=pretty for readable debugging output.")
+});
+var outputSchema = z.discriminatedUnion("success", [
+  z.object({
+    success: z.literal(true),
+    status: z.number(),
+    data: z.unknown()
+  }),
+  z.object({
+    success: z.literal(false),
+    status: z.number().optional(),
+    error: z.string()
+  })
+]);
+var requestFirebaseTool = new ConnectorTool({
+  name: "requestFirebase",
+  description: `Fetch public Hacker News data from the official Firebase API.
+Use this tool for normal dashboard data: top/new/best/ask/show/job story IDs, individual items, users, max item ID, and updates. The Firebase API is the preferred source whenever you do not need full-text search.
+
+This connector does not require API credentials, but a connectionId is still required to select the Hacker News data source. Keep dashboard calls bounded: fetch list IDs first, then fetch only the small slice of item details needed for the current view. Use searchAlgolia only when keyword, tag, or historical search is necessary.`,
+  inputSchema,
+  outputSchema,
+  async execute({ connectionId, path: path2, printPretty }, connections) {
+    const connection2 = connections.find((c) => c.id === connectionId);
+    if (!connection2) {
+      return {
+        success: false,
+        error: `Connection ${connectionId} not found`
+      };
+    }
+    console.log(
+      `[connector-request] hackernews/${connection2.name}: GET ${path2}`
+    );
+    try {
+      if (/^https?:\/\//i.test(path2)) {
+        return {
+          success: false,
+          error: "Absolute URLs are not allowed. Pass a Firebase path such as /topstories.json."
+        };
+      }
+      const url = new URL(
+        `${BASE_URL}${path2.startsWith("/") ? "" : "/"}${path2}`
+      );
+      if (printPretty) url.searchParams.set("print", "pretty");
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+      try {
+        const response = await fetch(url.toString(), {
+          method: "GET",
+          headers: { Accept: "application/json" },
+          signal: controller.signal
+        });
+        const data = await response.json();
+        if (!response.ok) {
+          return {
+            success: false,
+            status: response.status,
+            error: `HTTP ${response.status} ${response.statusText}`
+          };
+        }
+        return {
+          success: true,
+          status: response.status,
+          data
+        };
+      } finally {
+        clearTimeout(timeout);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, error: msg };
+    }
+  }
+});
+
+// ../connectors/src/connectors/hackernews/tools/search-algolia.ts
+import { z as z2 } from "zod";
+var BASE_URL2 = "https://hn.algolia.com/api/v1";
+var REQUEST_TIMEOUT_MS2 = 6e4;
+var inputSchema2 = z2.object({
+  toolUseIntent: z2.string().optional().describe(
+    "Brief description of what you intend to accomplish with this tool call"
+  ),
+  connectionId: z2.string().describe(
+    "ID of the Hacker News connection to use. This connector has no credentials, but the connection ID identifies the selected data source."
+  ),
+  endpoint: z2.enum(["search", "search_by_date", "items", "users"]).describe(
+    "Algolia API endpoint. Use search/search_by_date for keyword queries, items for /items/{id}, and users for /users/{username}. Prefer Firebase for non-search dashboard data."
+  ),
+  idOrUsername: z2.string().optional().describe(
+    "Required when endpoint is items or users. Pass the item id for items or the username for users."
+  ),
+  queryParams: z2.record(z2.string(), z2.string()).optional().describe(
+    "Query parameters for Algolia search. Common params: query, tags (e.g. story,comment,show_hn,ask_hn), numericFilters (e.g. created_at_i>1700000000), page, hitsPerPage. Keep hitsPerPage small for dashboards."
+  )
+});
+var outputSchema2 = z2.discriminatedUnion("success", [
+  z2.object({
+    success: z2.literal(true),
+    status: z2.number(),
+    data: z2.unknown()
+  }),
+  z2.object({
+    success: z2.literal(false),
+    status: z2.number().optional(),
+    error: z2.string()
+  })
+]);
+var searchAlgoliaTool = new ConnectorTool({
+  name: "searchAlgolia",
+  description: `Search Hacker News data through the Algolia-powered HN Search API.
+Use this tool only when Firebase cannot answer the question, such as keyword search, historical search, tag search, or sorting search hits by date. For top/new/best/Ask/Show/job dashboards and individual item/user lookups, prefer requestFirebase because it uses the official Hacker News Firebase API.
+
+Avoid frequent repeated Algolia searches from dashboards. Keep hitsPerPage small, page deliberately, and cache or reuse results in server logic when possible. The public search API may rate limit by IP when used heavily.`,
+  inputSchema: inputSchema2,
+  outputSchema: outputSchema2,
+  async execute({ connectionId, endpoint, idOrUsername, queryParams }, connections) {
+    const connection2 = connections.find((c) => c.id === connectionId);
+    if (!connection2) {
+      return {
+        success: false,
+        error: `Connection ${connectionId} not found`
+      };
+    }
+    console.log(
+      `[connector-request] hackernews/${connection2.name}: Algolia ${endpoint}`
+    );
+    try {
+      let path2 = `/${endpoint}`;
+      if (endpoint === "items" || endpoint === "users") {
+        if (!idOrUsername) {
+          return {
+            success: false,
+            error: `idOrUsername is required for endpoint ${endpoint}`
+          };
+        }
+        path2 += `/${encodeURIComponent(idOrUsername)}`;
+      }
+      const url = new URL(`${BASE_URL2}${path2}`);
+      if (queryParams) {
+        for (const [k, v] of Object.entries(queryParams)) {
+          url.searchParams.set(k, v);
+        }
+      }
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS2);
+      try {
+        const response = await fetch(url.toString(), {
+          method: "GET",
+          headers: { Accept: "application/json" },
+          signal: controller.signal
+        });
+        const data = await response.json();
+        if (!response.ok) {
+          return {
+            success: false,
+            status: response.status,
+            error: `HTTP ${response.status} ${response.statusText}`
+          };
+        }
+        return {
+          success: true,
+          status: response.status,
+          data
+        };
+      } finally {
+        clearTimeout(timeout);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, error: msg };
+    }
+  }
+});
+
+// ../connectors/src/connectors/hackernews/parameters.ts
+var parameters = {};
+
+// ../connectors/src/connectors/hackernews/index.ts
+var tools = {
+  requestFirebase: requestFirebaseTool,
+  searchAlgolia: searchAlgoliaTool
+};
+var hackerNewsConnector = new ConnectorPlugin({
+  slug: "hackernews",
+  authType: AUTH_TYPES.API_KEY,
+  name: "Hacker News",
+  description: "Connect to public Hacker News data using the official Firebase API, with optional Algolia-powered search when needed.",
+  iconUrl: "https://news.ycombinator.com/y18.svg",
+  parameters,
+  releaseFlag: { dev1: true, dev2: true, prod: false },
+  categories: ["scraping"],
+  onboarding: hackerNewsOnboarding,
+  systemPrompt: {
+    en: `### Tools
+
+- \`connector_hackernews-api-key_requestFirebase\`: Fetch public Hacker News data from the official Firebase API. Use this for story rankings, items, users, max item ID, and updates. Prefer this tool whenever keyword search is not required.
+- \`connector_hackernews-api-key_searchAlgolia\`: Search Hacker News data through the Algolia-powered search API. Use this only for keyword search, tag search, date-sorted search, or historical queries that Firebase cannot answer.
+
+### Business Logic
+
+The business logic type for this connector is "typescript". Use the connector SDK in your handler. This connector has no credential parameters, but still uses the API Key connector model so users can start immediately without entering a key.
+
+SDK methods (client created via \`connection(connectionId)\`):
+- \`client.requestFirebase(path)\` \u2014 low-level fetch against the official Firebase API
+- \`client.requestAlgolia(path, options?)\` \u2014 low-level fetch against HN Search powered by Algolia
+- \`client.getItem(id)\` \u2014 get a story, comment, job, poll, or poll option
+- \`client.getUser(username)\` \u2014 get a public HN user profile
+- \`client.getMaxItem()\` \u2014 get the current largest item ID
+- \`client.getUpdates()\` \u2014 get changed item IDs and profile IDs
+- \`client.getStoryIds(kind, options?)\` \u2014 get top/new/best/ask/show/job story IDs
+- \`client.getItems(ids, options?)\` \u2014 fetch item details with bounded concurrency
+- \`client.search(query, options?)\` \u2014 Algolia keyword search; use only when search is required
+
+For dashboards showing current top/new/best/Ask/Show/job stories, use Firebase list endpoints and then fetch only the item details needed for the visible view. Avoid unbounded item-tree traversal and avoid repeatedly hitting Algolia from render-time server logic. If the user asks for "search HN for ..." or historical keyword analysis, use Algolia with a small \`hitsPerPage\`.
+
+\`\`\`ts
+import type { Context } from "hono";
+import { connection } from "@squadbase/vite-server/connectors/hackernews";
+
+const hn = connection("<connectionId>");
+
+export default async function handler(c: Context) {
+  const { limit = 20 } = await c.req.json<{ limit?: number }>();
+
+  const ids = await hn.getStoryIds("top", { limit });
+  const stories = await hn.getItems(ids, {
+    limit,
+    concurrency: 5,
+  });
+
+  return c.json({ stories });
+}
+\`\`\`
+
+### Hacker News API Reference
+
+#### Official Firebase API
+- Base URL: \`https://hacker-news.firebaseio.com/v0\`
+- No authentication required
+- Items: \`/item/{id}.json\`
+- Users: \`/user/{username}.json\`
+- Story lists: \`/topstories.json\`, \`/newstories.json\`, \`/beststories.json\`, \`/askstories.json\`, \`/showstories.json\`, \`/jobstories.json\`
+- Live data: \`/maxitem.json\`, \`/updates.json\`
+
+#### HN Search powered by Algolia
+- Base URL: \`https://hn.algolia.com/api/v1\`
+- Use \`/search\` and \`/search_by_date\` for keyword queries
+- Common query parameters: \`query\`, \`tags\`, \`numericFilters\`, \`page\`, \`hitsPerPage\`
+- Prefer Firebase unless search or date filtering is genuinely needed`,
+    ja: `### \u30C4\u30FC\u30EB
+
+- \`connector_hackernews-api-key_requestFirebase\`: \u516C\u5F0F Firebase API \u304B\u3089\u516C\u958B Hacker News \u30C7\u30FC\u30BF\u3092\u53D6\u5F97\u3057\u307E\u3059\u3002\u30E9\u30F3\u30AD\u30F3\u30B0\u3001item\u3001user\u3001max item ID\u3001updates \u306E\u53D6\u5F97\u306B\u4F7F\u7528\u3057\u307E\u3059\u3002\u30AD\u30FC\u30EF\u30FC\u30C9\u691C\u7D22\u304C\u4E0D\u8981\u306A\u5834\u5408\u306F\u3053\u306E\u30C4\u30FC\u30EB\u3092\u512A\u5148\u3057\u3066\u304F\u3060\u3055\u3044\u3002
+- \`connector_hackernews-api-key_searchAlgolia\`: Algolia \u30D9\u30FC\u30B9\u306E\u691C\u7D22 API \u3067 Hacker News \u30C7\u30FC\u30BF\u3092\u691C\u7D22\u3057\u307E\u3059\u3002Firebase \u3067\u306F\u7B54\u3048\u3089\u308C\u306A\u3044\u30AD\u30FC\u30EF\u30FC\u30C9\u691C\u7D22\u3001\u30BF\u30B0\u691C\u7D22\u3001\u65E5\u4ED8\u9806\u691C\u7D22\u3001\u5C65\u6B74\u30AF\u30A8\u30EA\u304C\u5FC5\u8981\u306A\u5834\u5408\u306E\u307F\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002
+
+### Business Logic
+
+\u3053\u306E\u30B3\u30CD\u30AF\u30BF\u306E\u30D3\u30B8\u30CD\u30B9\u30ED\u30B8\u30C3\u30AF\u30BF\u30A4\u30D7\u306F "typescript" \u3067\u3059\u3002\u30CF\u30F3\u30C9\u30E9\u5185\u3067\u306F\u30B3\u30CD\u30AF\u30BFSDK\u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u3053\u306E\u30B3\u30CD\u30AF\u30BF\u306B\u306F\u8A8D\u8A3C\u30D1\u30E9\u30E1\u30FC\u30BF\u306F\u3042\u308A\u307E\u305B\u3093\u304C\u3001\u65E2\u5B58\u30E2\u30C7\u30EB\u306B\u5408\u308F\u305B\u3066 API Key \u30B3\u30CD\u30AF\u30BF\u3068\u3057\u3066\u6271\u3044\u3001\u30E6\u30FC\u30B6\u30FC\u306F\u30AD\u30FC\u5165\u529B\u306A\u3057\u3067\u3059\u3050\u958B\u59CB\u3067\u304D\u307E\u3059\u3002
+
+SDK\u30E1\u30BD\u30C3\u30C9 (\`connection(connectionId)\` \u3067\u4F5C\u6210\u3057\u305F\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8):
+- \`client.requestFirebase(path)\` \u2014 \u516C\u5F0F Firebase API \u3078\u306E\u4F4E\u30EC\u30D9\u30EBfetch
+- \`client.requestAlgolia(path, options?)\` \u2014 HN Search powered by Algolia \u3078\u306E\u4F4E\u30EC\u30D9\u30EBfetch
+- \`client.getItem(id)\` \u2014 story, comment, job, poll, poll option \u3092\u53D6\u5F97
+- \`client.getUser(username)\` \u2014 \u516C\u958B HN \u30E6\u30FC\u30B6\u30FC\u30D7\u30ED\u30D5\u30A3\u30FC\u30EB\u3092\u53D6\u5F97
+- \`client.getMaxItem()\` \u2014 \u73FE\u5728\u306E\u6700\u5927 item ID \u3092\u53D6\u5F97
+- \`client.getUpdates()\` \u2014 \u66F4\u65B0\u3055\u308C\u305F item ID \u3068 profile ID \u3092\u53D6\u5F97
+- \`client.getStoryIds(kind, options?)\` \u2014 top/new/best/ask/show/job \u306E story ID \u3092\u53D6\u5F97
+- \`client.getItems(ids, options?)\` \u2014 \u4E26\u5217\u6570\u3092\u5236\u9650\u3057\u3066 item \u8A73\u7D30\u3092\u53D6\u5F97
+- \`client.search(query, options?)\` \u2014 Algolia \u30AD\u30FC\u30EF\u30FC\u30C9\u691C\u7D22\u3002\u691C\u7D22\u304C\u5FC5\u8981\u306A\u5834\u5408\u306E\u307F\u4F7F\u7528
+
+\u73FE\u5728\u306E top/new/best/Ask/Show/job stories \u3092\u8868\u793A\u3059\u308B\u30C0\u30C3\u30B7\u30E5\u30DC\u30FC\u30C9\u3067\u306F\u3001Firebase \u306E\u30EA\u30B9\u30C8\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3092\u4F7F\u3044\u3001\u8868\u793A\u306B\u5FC5\u8981\u306A item \u8A73\u7D30\u3060\u3051\u3092\u53D6\u5F97\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u7121\u5236\u9650\u306E\u30B3\u30E1\u30F3\u30C8\u30C4\u30EA\u30FC\u8D70\u67FB\u3084\u3001\u30EC\u30F3\u30C0\u30EA\u30F3\u30B0\u6642\u30B5\u30FC\u30D0\u30FC\u30ED\u30B8\u30C3\u30AF\u304B\u3089\u306E Algolia \u9023\u6253\u306F\u907F\u3051\u3066\u304F\u3060\u3055\u3044\u3002\u30E6\u30FC\u30B6\u30FC\u304C\u300CHN\u3067\u691C\u7D22\u3057\u3066\u300D\u3084\u5C65\u6B74\u30AD\u30FC\u30EF\u30FC\u30C9\u5206\u6790\u3092\u6C42\u3081\u305F\u5834\u5408\u306F\u3001\u5C0F\u3055\u306A \`hitsPerPage\` \u3067 Algolia \u3092\u4F7F\u3044\u307E\u3059\u3002
+
+\`\`\`ts
+import type { Context } from "hono";
+import { connection } from "@squadbase/vite-server/connectors/hackernews";
+
+const hn = connection("<connectionId>");
+
+export default async function handler(c: Context) {
+  const { limit = 20 } = await c.req.json<{ limit?: number }>();
+
+  const ids = await hn.getStoryIds("top", { limit });
+  const stories = await hn.getItems(ids, {
+    limit,
+    concurrency: 5,
+  });
+
+  return c.json({ stories });
+}
+\`\`\`
+
+### Hacker News API \u30EA\u30D5\u30A1\u30EC\u30F3\u30B9
+
+#### \u516C\u5F0F Firebase API
+- \u30D9\u30FC\u30B9URL: \`https://hacker-news.firebaseio.com/v0\`
+- \u8A8D\u8A3C\u4E0D\u8981
+- Items: \`/item/{id}.json\`
+- Users: \`/user/{username}.json\`
+- Story lists: \`/topstories.json\`, \`/newstories.json\`, \`/beststories.json\`, \`/askstories.json\`, \`/showstories.json\`, \`/jobstories.json\`
+- Live data: \`/maxitem.json\`, \`/updates.json\`
+
+#### HN Search powered by Algolia
+- \u30D9\u30FC\u30B9URL: \`https://hn.algolia.com/api/v1\`
+- \u30AD\u30FC\u30EF\u30FC\u30C9\u691C\u7D22\u306B\u306F \`/search\` \u3068 \`/search_by_date\` \u3092\u4F7F\u7528
+- \u4E3B\u8981\u30AF\u30A8\u30EA\u30D1\u30E9\u30E1\u30FC\u30BF: \`query\`, \`tags\`, \`numericFilters\`, \`page\`, \`hitsPerPage\`
+- \u691C\u7D22\u3084\u65E5\u4ED8\u30D5\u30A3\u30EB\u30BF\u304C\u672C\u5F53\u306B\u5FC5\u8981\u306A\u5834\u5408\u3092\u9664\u304D Firebase \u3092\u512A\u5148\u3057\u3066\u304F\u3060\u3055\u3044`
+  },
+  tools,
+  setup: (params, ctx, config) => runSetupFlow(hackerNewsSetupFlow, params, ctx, config),
+  async checkConnection() {
+    try {
+      const res = await fetch(
+        "https://hacker-news.firebaseio.com/v0/maxitem.json",
+        {
+          method: "GET",
+          headers: { Accept: "application/json" }
+        }
+      );
+      if (!res.ok) {
+        const errorText = await res.text().catch(() => res.statusText);
+        return {
+          success: false,
+          error: `Hacker News API failed: HTTP ${res.status} ${errorText}`
+        };
+      }
+      return { success: true };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+});
+
+// src/connectors/create-connector-sdk.ts
+import { readFileSync } from "fs";
+import path from "path";
+
+// src/connector-client/env.ts
+function resolveEnvVar(entry, key, connectionId) {
+  const envVarName = entry.envVars[key];
+  if (!envVarName) {
+    throw new Error(`Connection "${connectionId}" is missing envVars mapping for key "${key}"`);
+  }
+  const value = process.env[envVarName];
+  if (!value) {
+    throw new Error(`Environment variable "${envVarName}" (for connection "${connectionId}", key "${key}") is not set`);
+  }
+  return value;
+}
+function resolveEnvVarOptional(entry, key) {
+  const envVarName = entry.envVars[key];
+  if (!envVarName) return void 0;
+  return process.env[envVarName] || void 0;
+}
+
+// src/connector-client/proxy-fetch.ts
+import { getContext } from "hono/context-storage";
+import { getCookie } from "hono/cookie";
+var APP_SESSION_COOKIE_NAME = "__Host-squadbase-session";
+var TABLEAU_SESSION_SENTINEL_URL = "squadbase://tableau-session/";
+function normalizeHeaders(input) {
+  const out = {};
+  if (!input) return out;
+  new Headers(input).forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+function extractInputUrl(input) {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.href;
+  return input.url;
+}
+function createSandboxProxyFetch(connectionId) {
+  return async (input, init) => {
+    const token = process.env.INTERNAL_SQUADBASE_OAUTH_MACHINE_CREDENTIAL;
+    const sandboxId = process.env.INTERNAL_SQUADBASE_SANDBOX_ID;
+    if (!token || !sandboxId) {
+      throw new Error(
+        "Connection proxy is not configured. Please check your deployment settings."
+      );
+    }
+    const originalUrl = extractInputUrl(input);
+    const baseDomain = process.env["SQUADBASE_PREVIEW_BASE_DOMAIN"] ?? "preview.app.squadbase.dev";
+    if (originalUrl === TABLEAU_SESSION_SENTINEL_URL) {
+      const sessionUrl = `https://${sandboxId}.${baseDomain}/_sqcore/connections/${connectionId}/tableau-session`;
+      return fetch(sessionUrl, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}` }
+      });
+    }
+    const originalMethod = init?.method ?? "GET";
+    const originalBody = init?.body ? JSON.parse(init.body) : void 0;
+    const proxyUrl = `https://${sandboxId}.${baseDomain}/_sqcore/connections/${connectionId}/request`;
+    return fetch(proxyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`
+      },
+      body: JSON.stringify({
+        url: originalUrl,
+        method: originalMethod,
+        headers: normalizeHeaders(init?.headers),
+        body: originalBody
+      })
+    });
+  };
+}
+function createDeployedAppProxyFetch(connectionId) {
+  const projectId = process.env["SQUADBASE_PROJECT_ID"];
+  if (!projectId) {
+    throw new Error(
+      "Connection proxy is not configured. Please check your deployment settings."
+    );
+  }
+  const baseDomain = process.env["SQUADBASE_APP_BASE_DOMAIN"] ?? "squadbase.app";
+  const proxyUrl = `https://${projectId}.${baseDomain}/_sqcore/connections/${connectionId}/request`;
+  const sessionUrl = `https://${projectId}.${baseDomain}/_sqcore/connections/${connectionId}/tableau-session`;
+  return async (input, init) => {
+    const originalUrl = extractInputUrl(input);
+    const c = getContext();
+    const appSession = getCookie(c, APP_SESSION_COOKIE_NAME);
+    if (!appSession) {
+      throw new Error(
+        "No authentication method available for connection proxy."
+      );
+    }
+    if (originalUrl === TABLEAU_SESSION_SENTINEL_URL) {
+      return fetch(sessionUrl, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${appSession}` }
+      });
+    }
+    const originalMethod = init?.method ?? "GET";
+    const originalBody = init?.body ? JSON.parse(init.body) : void 0;
+    return fetch(proxyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${appSession}`
+      },
+      body: JSON.stringify({
+        url: originalUrl,
+        method: originalMethod,
+        headers: normalizeHeaders(init?.headers),
+        body: originalBody
+      })
+    });
+  };
+}
+function createProxyFetch(connectionId) {
+  if (process.env.INTERNAL_SQUADBASE_SANDBOX_ID) {
+    return createSandboxProxyFetch(connectionId);
+  }
+  return createDeployedAppProxyFetch(connectionId);
+}
+
+// src/connectors/create-connector-sdk.ts
+function loadConnectionsSync() {
+  const filePath = process.env.CONNECTIONS_PATH ?? path.join(process.cwd(), ".squadbase/connections.json");
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function createConnectorSdk(plugin, createClient2) {
+  return (connectionId) => {
+    const connections = loadConnectionsSync();
+    const entry = connections[connectionId];
+    if (!entry) {
+      throw new Error(
+        `Connection "${connectionId}" not found in .squadbase/connections.json`
+      );
+    }
+    if (entry.connector.slug !== plugin.slug) {
+      throw new Error(
+        `Connection "${connectionId}" is not a ${plugin.slug} connection (got "${entry.connector.slug}")`
+      );
+    }
+    const params = {};
+    for (const param of Object.values(plugin.parameters)) {
+      if (param.required) {
+        params[param.slug] = resolveEnvVar(entry, param.slug, connectionId);
+      } else {
+        const val = resolveEnvVarOptional(entry, param.slug);
+        if (val !== void 0) params[param.slug] = val;
+      }
+    }
+    return createClient2(params, createProxyFetch(connectionId));
+  };
+}
+
+// src/connectors/entries/hackernews.ts
+var connection = createConnectorSdk(hackerNewsConnector, createClient);
+export {
+  connection
+};