v2 fully tested and production ready - beta tag removed - full demonstration with all artifacts and agent transcripts for a full project from ideation to dev pickup point

V2-FULL-DEMO-WALKTHROUGH/api-reference.md

@@ -0,0 +1,97 @@
+# BMad Hacker Daily Digest API Reference
+
+This document describes the external APIs consumed by the BMad Hacker Daily Digest application.
+
+## External APIs Consumed
+
+### Algolia Hacker News (HN) Search API
+
+- **Purpose:** Used to fetch the top Hacker News stories and the comments associated with each story.
+- **Base URL:** `http://hn.algolia.com/api/v1`
+- **Authentication:** None required for public search endpoints.
+- **Key Endpoints Used:**
+
+  - **`GET /search` (for Top Stories)**
+
+    - Description: Retrieves stories based on search parameters. Used here to get top stories from the front page.
+    - Request Parameters:
+      - `tags=front_page`: Required to filter for front-page stories.
+      - `hitsPerPage=10`: Specifies the number of stories to retrieve (adjust as needed, default is typically 20).
+    - Example Request (Conceptual using native `Workspace`):
+      ```typescript
+      // Using Node.js native Workspace API
+      const url =
+        "[http://hn.algolia.com/api/v1/search?tags=front_page&hitsPerPage=10](http://hn.algolia.com/api/v1/search?tags=front_page&hitsPerPage=10)";
+      const response = await fetch(url);
+      const data = await response.json();
+      ```
+    - Success Response Schema (Code: `200 OK`): See "Algolia HN API - Story Response Subset" in `docs/data-models.md`. Primarily interested in the `hits` array containing story objects.
+    - Error Response Schema(s): Standard HTTP errors (e.g., 4xx, 5xx). May return JSON with an error message.
+
+  - **`GET /search` (for Comments)**
+    - Description: Retrieves comments associated with a specific story ID.
+    - Request Parameters:
+      - `tags=comment,story_{storyId}`: Required to filter for comments belonging to the specified `storyId`. Replace `{storyId}` with the actual ID (e.g., `story_12345`).
+      - `hitsPerPage={maxComments}`: Specifies the maximum number of comments to retrieve (value from `.env` `MAX_COMMENTS_PER_STORY`).
+    - Example Request (Conceptual using native `Workspace`):
+      ```typescript
+      // Using Node.js native Workspace API
+      const storyId = "..."; // HN Story ID
+      const maxComments = 50; // From config
+      const url = `http://hn.algolia.com/api/v1/search?tags=comment,story_${storyId}&hitsPerPage=${maxComments}`;
+      const response = await fetch(url);
+      const data = await response.json();
+      ```
+    - Success Response Schema (Code: `200 OK`): See "Algolia HN API - Comment Response Subset" in `docs/data-models.md`. Primarily interested in the `hits` array containing comment objects.
+    - Error Response Schema(s): Standard HTTP errors.
+
+- **Rate Limits:** Subject to Algolia's public API rate limits (typically generous for HN search but not explicitly defined/guaranteed). Implementations should handle potential 429 errors gracefully if encountered.
+- **Link to Official Docs:** [https://hn.algolia.com/api](https://hn.algolia.com/api)
+
+### Ollama API (Local Instance)
+
+- **Purpose:** Used to generate text summaries for scraped article content and HN comment discussions using a locally running LLM.
+- **Base URL:** Configurable via the `OLLAMA_ENDPOINT_URL` environment variable (e.g., `http://localhost:11434`).
+- **Authentication:** None typically required for default local installations.
+- **Key Endpoints Used:**
+
+  - **`POST /api/generate`**
+    - Description: Generates text based on a model and prompt. Used here for summarization.
+    - Request Body Schema: See `OllamaGenerateRequest` in `docs/data-models.md`. Requires `model` (from `.env` `OLLAMA_MODEL`), `prompt`, and `stream: false`.
+    - Example Request (Conceptual using native `Workspace`):
+      ```typescript
+      // Using Node.js native Workspace API
+      const ollamaUrl =
+        process.env.OLLAMA_ENDPOINT_URL || "http://localhost:11434";
+      const requestBody: OllamaGenerateRequest = {
+        model: process.env.OLLAMA_MODEL || "llama3",
+        prompt: "Summarize this text: ...",
+        stream: false,
+      };
+      const response = await fetch(`${ollamaUrl}/api/generate`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(requestBody),
+      });
+      const data: OllamaGenerateResponse | { error: string } =
+        await response.json();
+      ```
+    - Success Response Schema (Code: `200 OK`): See `OllamaGenerateResponse` in `docs/data-models.md`. Key field is `response` containing the generated text.
+    - Error Response Schema(s): May return non-200 status codes or a `200 OK` with a JSON body like `{ "error": "error message..." }` (e.g., if the model is unavailable).
+
+- **Rate Limits:** N/A for a typical local instance. Performance depends on local hardware.
+- **Link to Official Docs:** [https://github.com/ollama/ollama/blob/main/docs/api.md](https://github.com/ollama/ollama/blob/main/docs/api.md)
+
+## Internal APIs Provided
+
+- **N/A:** The application is a self-contained CLI tool and does not expose any APIs for other services to consume.
+
+## Cloud Service SDK Usage
+
+- **N/A:** The application runs locally and uses the native Node.js `Workspace` API for HTTP requests, not cloud provider SDKs.
+
+## Change Log
+
+| Change        | Date       | Version | Description                     | Author      |
+| ------------- | ---------- | ------- | ------------------------------- | ----------- |
+| Initial draft | 2025-05-04 | 0.1     | Draft based on PRD/Epics/Models | 3-Architect |