@oboapp/source-nadezhda-org 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Extract the Nadezhda listing and article source into an independently versioned package.
+- Preserve source identity, literal identifiers, detail dates, content cleanup and Markdown through the shared browser helper.
+- Reuse one browser and keep two-second request pacing across listing and detail attempts.

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @oboapp/source-nadezhda-org
 
-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.
+Collects the Announcements and notices listing from Sofia district Nadezhda. Chromium reads the listing and each article. The package preserves the existing `nadezhda-org` identity, literal identifiers, detail title/date behavior, content cleanup and Markdown output.
+
+## Install and use
+
+```sh
+pnpm add @oboapp/source-nadezhda-org
+```
+
+Pass the runtime factory and isolated metadata to Obo's scheduled source runner:
+
+```ts
+import { createSource } from "@oboapp/source-nadezhda-org";
+import { metadata } from "@oboapp/source-nadezhda-org/metadata";
+```
+
+The metadata entrypoint can be loaded by the web catalog without loading browser dependencies. Direct SDK consumers call `await createSource({ locality: "bg.sofia" })`, followed by `discoverItems()` and `fetchItem(item)`. Always call `await source.close?.()` in `finally`.
+
+Obo owns historical lookups, validation, persistence, scheduling, ingestion and notifications. Updating this package preserves historical identifiers.
+
+## Collection behavior
+
+The legacy URL filter accepts the exact `nadezhda.sofia.bg` hostname and paths containing `/news/`. Exact duplicates are combined in their first listing position, matching the existing Map behavior. Query strings, fragments and percent-encoded spelling remain part of the identifier. Discovery returns identifiers only. A listing title is required to select an entry. Detail metadata comes only from the article page.
+
+Details require a non-empty page title and content. The detail date uses the existing Bulgarian numeric date conversion, including two-digit years and slash separators. An empty or unparseable detail date falls back to the current time. Cleaned HTML becomes Markdown with document links preserved.
+
+One Chromium browser is reused for the scan. Each listing/detail attempt closes its page and waits two seconds, including failed attempts. Image, media and font requests are blocked. Provider failures propagate to Obo, which records item failures and retries missing identifiers on a later scheduled scan.
+
+The runtime requires Node.js 20.3 or later and `@oboapp/source-web-utils` with Playwright 1.61.1 and its matching Chromium revision and system libraries. Keep that browser revision aligned with the deployment image.
+
+## Feed and API check
+
+The public announcement listing has no alternate feed links or AJAX collection endpoint. Checks of `/feed`, `/rss.xml` and `/atom.xml` did not expose a usable feed on 8 November 2026. Its scripts load jQuery and Bootstrap. This extraction preserves the existing browser listing.
+
+## Tests and release
+
+Tests protect literal URLs, filtering, duplicate behavior, detail-only metadata, date conversion, cleanup, retry/session handling and isolated ESM/CommonJS metadata. Synthetic DOM fixtures cover edge cases. Public listing and detail fragments captured on 8 November 2026 include identifiers and content frozen from the original source-specific extractors, date parser and Markdown builder. They run without provider requests.
+
+Run `pnpm check` from the sources repository root. Follow [the release procedure](../../RELEASING.md) for package checks, tarball inspection, publication and Obo integration.

package/dist/cjs/browser.d.ts

@@ -0,0 +1,3 @@
+import type { DataSource } from "@oboapp/source-sdk";
+import { type BrowserDependencies } from "@oboapp/source-web-utils/browser";
+export declare function createSourceWithDependencies(dependencies?: BrowserDependencies): DataSource;

package/dist/cjs/browser.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSourceWithDependencies = createSourceWithDependencies;
+const browser_1 = require("@oboapp/source-web-utils/browser");
+const INDEX_URL = "https://nadezhda.sofia.bg/%D0%BE%D0%B1%D1%8F%D0%B2%D0%B8-%D0%B8-%D1%81%D1%8A%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D1%8F";
+function acceptsUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.hostname === "nadezhda.sofia.bg" && parsed.pathname.includes("/news/");
+    }
+    catch {
+        return false;
+    }
+}
+function createSourceWithDependencies(dependencies) {
+    return (0, browser_1.createBrowserSource)({
+        indexUrl: INDEX_URL,
+        selectors: {
+            INDEX: {
+                POST_CONTAINER: "li.shadow-sm",
+                POST_LINK: 'a[href*="/news/"]',
+                POST_DATE: "small, .small, .date, [class*=date]",
+                POST_TITLE: "a",
+            },
+            POST: {
+                CONTENT: ".justify-content-center > div > .bg-white.mt-2 > .p-2, .justify-content-center > div .p-2",
+                TITLE: ".justify-content-center > div > h1.pl-2, .justify-content-center h1.pl-2",
+                DATE: ".justify-content-center > div > .bg-white.mt-2 > small.pl-2, .justify-content-center small.pl-2",
+            },
+        },
+        urlFilter: acceptsUrl,
+        dedupe: "last",
+        unwantedElements: ["script", "style", "nav", "footer", ".breadcrumb"],
+    }, dependencies);
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,2 @@
+import type { CreateSource } from "@oboapp/source-sdk";
+export declare const createSource: CreateSource;

package/dist/cjs/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSource = void 0;
+const browser_js_1 = require("./browser.js");
+const createSource = () => {
+    return (0, browser_js_1.createSourceWithDependencies)();
+};
+exports.createSource = createSource;

package/dist/cjs/metadata.d.ts

@@ -0,0 +1,2 @@
+import type { SourceMetadata } from "@oboapp/source-sdk/metadata";
+export declare const metadata: SourceMetadata;

package/dist/cjs/metadata.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metadata = void 0;
+exports.metadata = {
+    id: "nadezhda-org",
+    url: "https://nadezhda.sofia.bg/%D0%BE%D0%B1%D1%8F%D0%B2%D0%B8-%D0%B8-%D1%81%D1%8A%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D1%8F",
+    name: 'Столична община, Район "Надежда"',
+    localities: ["bg.sofia"],
+};

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/browser.d.ts

@@ -0,0 +1,3 @@
+import type { DataSource } from "@oboapp/source-sdk";
+import { type BrowserDependencies } from "@oboapp/source-web-utils/browser";
+export declare function createSourceWithDependencies(dependencies?: BrowserDependencies): DataSource;

package/dist/esm/browser.js

@@ -0,0 +1,32 @@
+import { createBrowserSource } from "@oboapp/source-web-utils/browser";
+const INDEX_URL = "https://nadezhda.sofia.bg/%D0%BE%D0%B1%D1%8F%D0%B2%D0%B8-%D0%B8-%D1%81%D1%8A%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D1%8F";
+function acceptsUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.hostname === "nadezhda.sofia.bg" && parsed.pathname.includes("/news/");
+    }
+    catch {
+        return false;
+    }
+}
+export function createSourceWithDependencies(dependencies) {
+    return createBrowserSource({
+        indexUrl: INDEX_URL,
+        selectors: {
+            INDEX: {
+                POST_CONTAINER: "li.shadow-sm",
+                POST_LINK: 'a[href*="/news/"]',
+                POST_DATE: "small, .small, .date, [class*=date]",
+                POST_TITLE: "a",
+            },
+            POST: {
+                CONTENT: ".justify-content-center > div > .bg-white.mt-2 > .p-2, .justify-content-center > div .p-2",
+                TITLE: ".justify-content-center > div > h1.pl-2, .justify-content-center h1.pl-2",
+                DATE: ".justify-content-center > div > .bg-white.mt-2 > small.pl-2, .justify-content-center small.pl-2",
+            },
+        },
+        urlFilter: acceptsUrl,
+        dedupe: "last",
+        unwantedElements: ["script", "style", "nav", "footer", ".breadcrumb"],
+    }, dependencies);
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+import type { CreateSource } from "@oboapp/source-sdk";
+export declare const createSource: CreateSource;

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+import { createSourceWithDependencies } from "./browser.js";
+export const createSource = () => {
+    return createSourceWithDependencies();
+};

package/dist/esm/metadata.d.ts

@@ -0,0 +1,2 @@
+import type { SourceMetadata } from "@oboapp/source-sdk/metadata";
+export declare const metadata: SourceMetadata;

package/dist/esm/metadata.js

@@ -0,0 +1,6 @@
+export const metadata = {
+    id: "nadezhda-org",
+    url: "https://nadezhda.sofia.bg/%D0%BE%D0%B1%D1%8F%D0%B2%D0%B8-%D0%B8-%D1%81%D1%8A%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D1%8F",
+    name: 'Столична община, Район "Надежда"',
+    localities: ["bg.sofia"],
+};

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@oboapp/source-nadezhda-org",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Webpage source for Sofia district Nadezhda",
+  "main": "./dist/cjs/index.js",
+  "license": "Unlicense",
+  "type": "module",
+  "types": "./dist/cjs/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oboapp/sources.git",
+    "directory": "packages/source-nadezhda-org"
+  },
+  "engines": {
+    "node": ">=20.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "typesVersions": {
+    "*": {
+      "metadata": [
+        "dist/cjs/metadata.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./metadata": {
+      "import": {
+        "types": "./dist/esm/metadata.d.ts",
+        "default": "./dist/esm/metadata.js"
+      },
+      "require": {
+        "types": "./dist/cjs/metadata.d.ts",
+        "default": "./dist/cjs/metadata.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@oboapp/source-sdk": "0.1.1",
+    "@oboapp/source-web-utils": "0.2.0"
+  },
+  "devDependencies": {
+    "happy-dom": "20.0.11",
+    "playwright": "1.61.1"
+  },
+  "scripts": {
+    "test": "tsc -p test/tsconfig.json && tsx --test test/*.test.ts",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/finalize-build.mjs"
+  }
 }