@czlonkowski/n8n-nodes-librus 0.1.0

package/docs/architecture.md

@@ -0,0 +1,53 @@
+# Architecture and evidence
+
+## Execution contract
+
+A programmatic node is necessary because login, redirects, cookie handling and paginated message retrieval are dependent requests. `Librus.node.ts` owns n8n parameters, credentials, item pairing and conversion of safe errors. `LibrusClient.ts` owns the session and response validation. `transport.ts` adapts n8n's modern execution helper and legacy-only credential-test helper.
+
+No process-global cache, workflow static data, environment secret or file stores authentication state. Each client owns a `tough-cookie` jar. The node never outputs cookies, passwords, raw HTTP errors or login response bodies. Node errors are reconstructed from fixed messages. Downstream output deliberately includes message metadata and optional preview or full content, identified by `contentSource`. Preview remains the default for existing workflows.
+
+## Observed community protocol
+
+1. GET `https://synergia.librus.pl/loguj/portalRodzina` and follow the browser authorization redirects.
+2. POST form fields `action=login`, `login`, and `pass` to the resulting validated HTTPS `api.librus.pl/OAuth/Authorization` route.
+3. Follow the returned `goTo` authorization continuation. A successful flow may terminate at Synergia `/loguj/portalRodzina`; this callback is allowed, with TokenInfo and inbox access still checked afterward. A terminal verification page stops with `ACTION_REQUIRED`.
+4. Request `/gateway/api/2.0/Auth/TokenInfo/` on Synergia.
+5. Initialize messages through `https://synergia.librus.pl/wiadomosci3`.
+6. GET `https://wiadomosci.librus.pl/api/inbox/messages?page=1&limit=50` and paginate its `data` array. Its `content` field is a truncated preview.
+7. Only when Include Content is enabled and Content Source is Full Message, fetch `/api/inbox/messages/{messageId}` for each selected message in the same session. Validate the returned ID and decode the case-sensitive `data.Message` field as the full body.
+
+These are unofficial website routes, not a contracted public API. No verified refresh-token operation is implemented. TokenInfo success is not sufficient proof of inbox access; the credential test also validates a listing response.
+
+## Boundaries
+
+HTTPS and four exact Librus hostnames are allowlisted. Every redirect is checked before a request is issued. Legacy HTTP Location headers targeting exact allowlisted hosts are upgraded to HTTPS before sending; no request is made over HTTP. URL credentials and non-default ports are rejected. Password-bearing POSTs are restricted to the authorization route and never automatically redirected or replayed. Cookies are obtained from the jar separately for each URL.
+
+Requests time out after at most 15 seconds. An operation is bounded to 120 seconds and 100 requests, including a possible second login. Redirect chains stop after 10 redirects. A recognized session expiry during a scan allows one fresh login and restarts the scan, discarding partial results. Generic HTML, malformed JSON and schema mismatches fail rather than returning an empty inbox. A short page is treated as end-of-list; this assumption must be verified live. Pagination is not a transactional snapshot when messages arrive mid-scan.
+
+No scheduling or cross-execution deduplication lives in the action node. The separate Librus Trigger owns account-scoped discovery history; downstream workflows own delivery state. Reading listing entries does not explicitly call a mark-read endpoint; side effects still need live measurement.
+
+## Source references
+
+- [FlakM/librus-rs authentication](https://github.com/FlakM/librus-rs/blob/224bd49c613a2f416f757aab6ad44c40ac2b4d9b/src/lib.rs) and [message schema](https://github.com/FlakM/librus-rs/blob/224bd49c613a2f416f757aab6ad44c40ac2b4d9b/src/structs/messages.rs): browser OAuth and new inbox route.
+- [Mati365/librus-api](https://github.com/Mati365/librus-api/blob/9b47c3c460728fa674e6e6aba530558dbd0b486f/lib/api.js): authorization URL validation and current login sequence. Its legacy inbox is not used here.
+- [n8n community-node development](https://docs.n8n.io/integrations/creating-nodes/overview/): package and node conventions.
+
+Implementation was written independently from these protocol observations. Source inspection and offline fixture success are not live integration evidence.
+
+## Full message retrieval
+
+Complete pagination and deduplication before issuing detail requests. Reject more than 50 selected messages before any detail request. Fetch sequentially within the existing 100-request/120-second operation budget, with one recognized session-expiry recovery for the whole operation. Fail on missing/mismatched details or invalid base64; never silently fall back to preview. No partial output is emitted. Detail requests may affect unread state; previous reads cannot be rolled back on a later failure. The returned readDate remains the pre-detail listing snapshot. Message IDs are restricted to safe alphanumeric, underscore and hyphen path segments before detail retrieval.
+
+## Read filters and single-message content
+
+Get Many filters listing metadata locally using readDate (null/absent/empty means unread) before applying the requested result limit. Pagination progress is tracked separately from matching results, so a full page of read messages does not prematurely terminate an unread scan. Full bodies are requested only after selection. During session recovery after unread/full selection, retain the selected IDs: re-filtering the inbox could lose messages already marked read by earlier detail requests. Other scan recovery retains the existing restart behaviour. Get Content takes a validated ID and returns only messageId/content/contentSource; it shares the guarded detail route and one-session-recovery limit.
+
+## Polling contract
+
+LibrusTrigger implements IPollFunctions with polling:true; n8n injects Poll Times. Automatic polls scan the whole inbox across all read statuses. The first complete scan records a silent baseline. Subsequent complete scans emit unseen IDs and retain a union of up to 10000 IDs; reaching capacity or encountering invalid state fails without mutating history. A SHA-256 account fingerprint uses credential ID and username, not password, so password rotation does not replay messages. Changing account establishes a new baseline. Manual mode retrieves a single preview sample and never accesses static data.
+
+State comparison and assignment occur after the asynchronous scan, with no await between them. This avoids duplicate emission for overlapping calls sharing the same state object. It does not provide distributed locking for stale copies or multi-instance executions. The cursor advances before downstream delivery; a failed downstream action must be recovered through execution retry, not another poll. IDs of messages moved out of the inbox remain in history. This is discovery deduplication, not a transactional outbox or an exactly-once guarantee.
+
+Verified installed n8n 2.37.10 code: n8n-core/dist/nodes-loader/directory-loader.js injects commonPollingParameters; active-workflow-triggers.js runs an activation poll; n8n/dist/workflows/triggers/workflow-trigger-activator.js saves static data after registration. workflow-execution.service.js and poll-cursor.service.js commit a durable cursor with the execution before downstream processing where durable scheduling is enabled. Legacy and durable behaviour depends on host configuration; no host-internal APIs are imported by this package.
+
+Public Librus frontend research (2026-09-07): https://wiadomosci.librus.pl/nowy/inbox serves App-DRe0BPBk.js under /nowy/assets/. Its UI includes an unreadOnly filter, a GET inbox detail route and unread counts, but the inspected code exposes no mark-unread action. Only protocol observations were used; no frontend implementation was copied. Local filtering uses the listing contract already exercised by the client rather than relying on another unverified server query parameter.

package/docs/live-verification.md

@@ -0,0 +1,23 @@
+# Live verification checklist
+
+Status: **partially verified on 2026-09-07**. A metadata-only execution and an explicit Full Message execution succeeded on one account. The full detail body was longer than the matching preview. Unread-state preservation, broader content-format coverage and pagination remain unverified. Never paste a password or raw message response into a bug report, fixture or terminal command.
+
+1. With Node.js 24 active, run `N8N_LISTEN_ADDRESS=127.0.0.1 N8N_PORT=5689 npm run dev`. The isolated profile lives in `../.n8n-librus-dev`; never put it inside this repository. Create credentials inside the n8n UI.
+2. Run the credential test. Record only success or the sanitized error code. Confirm the login works on accounts with and without optional verification prompts; stop when the website requires user action.
+3. Note the IDs and unread status of a small known set in the Librus UI. Execute Get Many with Limit 10 and Include Content off. Compare sender, subject, ID and dates without saving a private fixture.
+4. Reopen the website and verify unread status is unchanged. This must pass before claiming that polling preserves unread state.
+5. Enable Include Content and select Content Source → Full Message for an already-read known message and compare the complete body, Unicode and HTML with the UI. Test a message with an attachment; verify attachment presence only. Confirm whether base64 padding and nullable fields match the strict schema.
+6. Test a second page and end-of-list behaviour. Verify the server honours `limit` and whether short pages always mean the end. Test duplicate IDs and arrival of a new message between scans.
+7. Use controlled synthetic transport tests for expiry and 429; do not deliberately hammer a live account or repeatedly submit wrong passwords.
+8. Before unattended scheduling, measure ordinary session lifetime, login effects on the browser/mobile app, practical polling frequency and concurrent account behaviour. The trigger implements ID deduplication and an initial baseline; verify persistence in the target deployment. Add a workflow error path for authentication failures and incomplete scans.
+
+Do not store cookies in workflow static data or node output when adding session reuse. Do not label sessions as OAuth refresh tokens without observing and verifying a supported refresh operation.
+
+## New operations and trigger acceptance
+
+- Get Many with Read Status Unread must exclude known read messages and apply Limit to matching entries, including across pages. Compare metadata-only results before enabling full-body retrieval.
+- Use Get Content on an already-read ID. Compare its body with Full Message from Get Many without exporting private content.
+- Manually test Librus Trigger: one sample (or none for an empty inbox), no automatic polling or history updates.
+- In a deliberately activated test workflow with no outbound action, confirm the first automatic poll emits no old messages; one newly received message emits once, even if read before polling. Do not send test messages to others without authorization.
+- Restart the test instance with persistent storage; confirm no replay. Exercise downstream-failure recovery with synthetic data and execution retry.
+- Check account-switch baseline, an inbox beyond the page cap, and ordinary session/browser effects before enabling unattended use.

package/docs/logo.md

@@ -0,0 +1,11 @@
+# Node logo
+
+The node and credentials share `nodes/Librus/librus.png`. The transparent PNG combines an open book, envelope and coral unread dot. A midnight teal tile keeps the cream and seafoam mark visible on light and dark n8n canvases. The README uses the same asset.
+
+Created with the built-in OpenAI image generation tool on 2026-09-07. This is an independent community mark, not the official LIBRUS logo. No LIBRUS source assets were used.
+
+## Generation prompt
+
+Use case: logo-brand. Create ONE finished square icon for an open-source n8n node that reads school journal messages, called Librus community integration. Deliver a clean production logo asset, NOT a mockup or presentation sheet. No text, no letters, no watermark. A clever minimal geometric symbol merging an open book and an envelope: two broad creamy-white page shapes form a central V/envelope fold, with a single small warm coral unread-notification dot at the upper right. Place it inside a deep midnight teal rounded-square tile. A small seafoam/teal accent on one page gives depth through flat overlapping shapes only. Outer canvas genuinely transparent, tile fills about 88 percent of square with balanced clear margin. Friendly, precise, polished contemporary open-source software identity. Flat vector-like rendering, crisp curves, generous negative space, no gradients, no 3D, no textures, no drop shadows, no thin lines, at most four solid colors. Excellent legibility at 24 to 60 pixels, attractive on both white and dark gray UI. Original independent symbol; do not reproduce the official LIBRUS logo. Square 1024x1024 output.
+
+The returned PNG is 1254 by 1254 pixels with alpha, preserved unchanged. n8n and the README size it at display time.

package/docs/verification.md

@@ -0,0 +1,41 @@
+# Bootstrap verification — 2026-09-07
+
+- Node.js 24.20.0, TypeScript 5.9.2, @n8n/node-cli 0.46.4, n8n-workflow development types 2.38.1.
+- `npm run check`: clean lint and TypeScript build; 35 synthetic offline tests passed.
+- Tests cover authentication, host-scoped cookies, unsafe redirects, password POST replay prevention, bounded pagination, deduplication, expiry retry, marked login pages, optional fields, base64/UTF-8 validation, safe timeouts and sanitized n8n execution/credential-test errors.
+- Official CLI development mode started n8n 2.37.10 on loopback port 5689 with a separate temporary profile. `/healthz` returned HTTP 200. The generated n8n node and credential registries contained `CUSTOM.librus` and `librusSessionApi`. No user account setup, workflow activation or real Librus login was performed.
+- `npm pack` produced an installable tarball; the manifest entry points, icons and documentation were inspected. Tests, node_modules, development profiles and compiler caches are excluded.
+- One independent GPT-5.6 Sol reader reviewed the client, adapters, credentials and protocol sources. Optional-field, timeout-boundary and login-form classification findings were addressed and covered by regression tests.
+- Runtime audit: zero reported vulnerabilities. Development tooling: ten moderate advisories remain after updating n8n-workflow to remove the initial four high-severity reports; see SECURITY.md.
+
+These checks establish package loading and offline behaviour. They do not establish successful live authentication, body completeness, unread-state preservation, pagination semantics or safe unattended polling frequency.
+
+## Live login correction — 2026-09-07
+
+The user's manual n8n workflow initially returned ACTION_REQUIRED. A diagnostic retry identified the terminal page as the Synergia OAuth callback. The client had incorrectly classified every `/loguj/` path as a login prompt. Allowing the callback exposed a legacy HTTP redirect during the subsequent handoff. Trusted-host HTTP redirects are now upgraded to HTTPS before any request; all other URL checks remain in force.
+
+After both fixes, the same workflow succeeded with Limit 1 and Include Content off. The output contained one item with messageId, senderName and readDate fields. Credentials were used through the existing n8n credential entry; no password, cookie, authorization code or message value was copied into this repository or these notes. Browser-session effects, unread-state preservation, content completeness and live pagination were not measured.
+
+`npm run check` passed all 40 tests, including successful callback handling, failed post-callback access, retained login challenges, redacted diagnostics and HTTP-to-HTTPS redirect upgrade boundaries.
+
+## Full content retrieval — 2026-09-07
+
+The listing content was confirmed to be a truncated preview. Added explicit Preview/Full Message selection while retaining Preview as the default. Full Message retrieves the case-sensitive data.Message field from the message detail route, only after listing pagination, limit and deduplication complete. An explicit cap of 50 selected messages bounds extra requests.
+
+The existing manual n8n workflow succeeded with Limit 1, Include Content enabled and Content Source set to Full Message. The chosen already-read message matched the user's example. Its preview had 95 characters; its detail body had 463 characters and began with the entire preview. Only lengths and comparison results were recorded; no message contents or identifiers were added to the repository. Unread-state side effects and comparison against the full website rendering remain unverified.
+
+`npm run check` passed 55 tests, including backward-compatible preview behaviour, full body decoding, selection before hydration, malformed/mismatched detail responses, no partial/fallback output, safety limits and session recovery during detail retrieval.
+
+## Read filters and polling trigger — 2026-09-07
+
+Added All/Unread/Read filtering before result limits, Get Content by ID, and a separate registered Librus Trigger. One GPT-5.6 Sol reader traced the installed n8n 2.37.10 polling/runtime persistence contract; the parent verified the decisive activation/save and cursor-before-delivery source paths and implemented the changes.
+
+`npm run check` passed 73 synthetic tests. New tests cover nonmatching full pages, filtered limits and hydration, invalid options, single-ID dispatch, unread selection preservation during detail-session recovery, initial silent baseline, serialized restart, read-state changes, account changes, bounded/corrupt state, manual sample isolation, failed scans, shared-state overlapping calls and duplicate risk with independent stale copies. Downstream retry semantics are established from runtime source inspection and the poll cursor contract, not a live failed-notification trial.
+
+The development watcher reported successful builds and hot reloads. A manual browser acceptance test could not be completed after the browser automation connection detached; a fresh-tab attempt also timed out. No live unread-filter result, scheduled message-arrival event or restart persistence trial is claimed for these new features. No workflow was activated and no message or notification was sent. Existing n8n credentials were not extracted. Mark-as-unread is not implemented because the inspected public Librus frontend exposed no matching action.
+
+## Manual npm publishing — 2026-09-07
+
+The unscoped n8n-nodes-librus name belongs to a previous unrelated package. The manifest and lockfile now use @czlonkowski/n8n-nodes-librus at 0.1.0; the GitHub repository keeps its existing name. npm reports no public scoped package entry; authenticated publishing access still needs confirmation.
+
+Added scripts/release.mjs and npm run release, with a --dry-run option. The actual dry run completed dependency installation, clean lint/build, all 73 tests, inspection of the 29-file archive and npm publish --dry-run with public access. No version was published. Invalid arguments and dirty-working-tree publication guards were also exercised. The script publishes the inspected tarball and does not create a release pipeline, Git tag or GitHub release. Local npm authentication was absent during verification.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@czlonkowski/n8n-nodes-librus",
+  "version": "0.1.0",
+  "description": "Nieoficjalny węzeł społecznościowy n8n do odczytywania wiadomości z Librus Synergia.",
+  "license": "MIT",
+  "keywords": [
+    "n8n-community-node-package",
+    "librus",
+    "synergia"
+  ],
+  "author": {
+    "name": "Romuald Członkowski",
+    "email": "56956555+czlonkowski@users.noreply.github.com"
+  },
+  "scripts": {
+    "build": "n8n-node build",
+    "dev": "n8n-node dev --custom-user-folder ../.n8n-librus-dev",
+    "lint": "n8n-node lint",
+    "lint:fix": "n8n-node lint --fix",
+    "format": "prettier --write credentials nodes tests .github package.json tsconfig.json eslint.config.mjs",
+    "test": "npm run build && node --test tests/*.test.cjs",
+    "check": "npm run lint && npm test",
+    "prepublishOnly": "npm run check",
+    "prepack": "npm run build",
+    "release": "node scripts/release.mjs"
+  },
+  "files": [
+    "dist/nodes",
+    "dist/credentials",
+    "LICENSE",
+    "NOTICE.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "docs"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "strict": false,
+    "credentials": [
+      "dist/credentials/LibrusSessionApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/Librus/Librus.node.js",
+      "dist/nodes/Librus/LibrusTrigger.node.js"
+    ]
+  },
+  "devDependencies": {
+    "@n8n/node-cli": "0.46.4",
+    "@types/node": "24.3.0",
+    "eslint": "9.32.0",
+    "n8n-workflow": "2.38.1",
+    "prettier": "3.6.2",
+    "typescript": "5.9.2"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "tough-cookie": "6.0.2"
+  },
+  "homepage": "https://github.com/czlonkowski/n8n-nodes-librus#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/czlonkowski/n8n-nodes-librus.git"
+  },
+  "bugs": {
+    "url": "https://github.com/czlonkowski/n8n-nodes-librus/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}