notefeed 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel Bruckner
+
+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

@@ -0,0 +1,19 @@
+# notefeed
+
+Post markdown notes to a [notefeed](https://github.com/Marceltov/notefeed) server from Node or the command line. No dependencies; Node 20 or newer.
+
+```sh
+npm install notefeed
+export NOTEFEED_URL=https://notes.example.com NOTEFEED_TOKEN=...
+npx notefeed post "# Backup finished"
+backup.sh 2>&1 | npx notefeed post -
+```
+
+```js
+import { Client } from "notefeed";
+
+const note = await new Client().post("# Deploy done\nversion 1.4.2"); // reads NOTEFEED_URL / NOTEFEED_TOKEN
+console.log(note.url);
+```
+
+Full documentation: https://marceltov.github.io/notefeed/clients/

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+process.exitCode = await main(process.argv.slice(2));

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+type Io = {
+    stdin: AsyncIterable<Buffer | string>;
+    stdout: {
+        write(s: string): unknown;
+    };
+    stderr: {
+        write(s: string): unknown;
+    };
+};
+/** Returns the exit code: 0 ok, 1 server/network error, 2 usage/config error. */
+export declare function main(argv: string[], io?: Io): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,85 @@
+/** `notefeed post ...` — post a note from the command line. */
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { Client, ConfigError, NotefeedError } from "./client.js";
+class UsageError extends Error {
+}
+const USAGE = 'usage: notefeed post <text | - | --file PATH> [--url URL] [--token TOKEN]';
+/** Returns the exit code: 0 ok, 1 server/network error, 2 usage/config error. */
+export async function main(argv, io = process) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: asPositionals(argv),
+            allowPositionals: true,
+            options: {
+                url: { type: "string" },
+                token: { type: "string" },
+                file: { type: "string" },
+                version: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+        if (values.help) {
+            io.stdout.write(`${USAGE}\n`);
+            return 0;
+        }
+        if (values.version) {
+            const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+            io.stdout.write(`notefeed ${pkg.version}\n`);
+            return 0;
+        }
+        const [command, text, ...rest] = positionals;
+        if (command !== "post" || rest.length)
+            throw new UsageError(USAGE);
+        const markdown = await read(text, values.file, io);
+        const note = await new Client({ url: values.url, token: values.token }).post(markdown);
+        io.stdout.write(`${note.url}\n`);
+        return 0;
+    }
+    catch (e) {
+        io.stderr.write(`notefeed: ${e.message.split("\n")[0]}\n`);
+        if (e instanceof ConfigError || e instanceof UsageError)
+            return 2;
+        if (e instanceof NotefeedError)
+            return 1;
+        return 2; // parseArgs rejects unknown options with a TypeError
+    }
+}
+async function read(text, file, io) {
+    if (file) {
+        try {
+            return utf8(await readFile(file), file);
+        }
+        catch (e) {
+            if (e instanceof UsageError)
+                throw e;
+            throw new UsageError(`cannot read ${file}: ${e.code ?? e.message}`);
+        }
+    }
+    if (text === "-") {
+        const chunks = [];
+        for await (const c of io.stdin)
+            chunks.push(typeof c === "string" ? Buffer.from(c) : c);
+        return utf8(Buffer.concat(chunks), "stdin");
+    }
+    if (text === undefined)
+        throw new UsageError('give the note text, "-" for stdin, or --file PATH');
+    return text;
+}
+function utf8(bytes, source) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new UsageError(`${source} is not UTF-8`);
+    }
+}
+// Note text like "- buy milk" starts with "-" but is not an option; argparse (Python CLI) treats an
+// argument with whitespace as positional, so do the same by moving such arguments after "--".
+function asPositionals(argv) {
+    if (argv.includes("--"))
+        return argv;
+    const text = argv.filter((a) => /^-.*\s/.test(a));
+    return [...argv.filter((a) => !/^-.*\s/.test(a)), "--", ...text];
+}

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+/** A tiny client for notefeed's POST /api/notes. No dependencies; uses the global fetch. */
+export type Note = {
+    id: string;
+    url: string;
+};
+export type ClientOptions = {
+    url?: string;
+    token?: string;
+    timeoutMs?: number;
+};
+/** Any failure talking to notefeed. `status` is the HTTP status, or null (network, config). */
+export declare class NotefeedError extends Error {
+    readonly status: number | null;
+    constructor(message: string, status?: number | null);
+}
+/** URL or token missing. */
+export declare class ConfigError extends NotefeedError {
+}
+/** The server rejected the note (400, 415): empty, not UTF-8, wrong type. */
+export declare class InvalidNoteError extends NotefeedError {
+}
+/** Missing or wrong token (401). */
+export declare class AuthError extends NotefeedError {
+}
+/** The note is over the server's size limit (413). */
+export declare class NoteTooLargeError extends NotefeedError {
+}
+export declare class Client {
+    readonly url: string;
+    private readonly token;
+    private readonly timeoutMs;
+    constructor(options?: ClientOptions);
+    post(markdown: string): Promise<Note>;
+}
+/** Post one note. Options go to Client (url, token, timeoutMs). */
+export declare function post(markdown: string, options?: ClientOptions): Promise<Note>;

package/dist/client.js

@@ -0,0 +1,87 @@
+/** A tiny client for notefeed's POST /api/notes. No dependencies; uses the global fetch. */
+/** Any failure talking to notefeed. `status` is the HTTP status, or null (network, config). */
+export class NotefeedError extends Error {
+    status;
+    constructor(message, status = null) {
+        super(message);
+        this.status = status;
+        this.name = new.target.name;
+    }
+}
+/** URL or token missing. */
+export class ConfigError extends NotefeedError {
+}
+/** The server rejected the note (400, 415): empty, not UTF-8, wrong type. */
+export class InvalidNoteError extends NotefeedError {
+}
+/** Missing or wrong token (401). */
+export class AuthError extends NotefeedError {
+}
+/** The note is over the server's size limit (413). */
+export class NoteTooLargeError extends NotefeedError {
+}
+const ERRORS = {
+    400: InvalidNoteError,
+    415: InvalidNoteError,
+    401: AuthError,
+    413: NoteTooLargeError,
+};
+function setting(value, env) {
+    const v = value || process.env[env] || "";
+    if (!v)
+        throw new ConfigError(`no ${env.split("_")[1].toLowerCase()} given; pass it or set ${env}`);
+    return v;
+}
+export class Client {
+    url;
+    token;
+    timeoutMs;
+    constructor(options = {}) {
+        this.url = setting(options.url, "NOTEFEED_URL").replace(/\/+$/, "");
+        this.token = setting(options.token, "NOTEFEED_TOKEN").trim();
+        // Never echo the value: it would end up in terminals and CI logs.
+        if (/[\x00-\x1f\x7f]/.test(this.token))
+            throw new ConfigError("NOTEFEED_TOKEN contains invalid characters");
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+    }
+    async post(markdown) {
+        let res;
+        try {
+            res = await fetch(`${this.url}/api/notes`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${this.token}`, "Content-Type": "text/markdown; charset=utf-8" },
+                body: new TextEncoder().encode(markdown),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (e) {
+            const cause = e.cause;
+            const reason = cause?.code ?? cause?.message ?? e.message;
+            throw new NotefeedError(`could not reach ${this.url}: ${reason}`);
+        }
+        const text = await res.text();
+        if (!res.ok) {
+            let message;
+            try {
+                message = JSON.parse(text).error;
+                if (typeof message !== "string")
+                    throw new Error();
+            }
+            catch {
+                message = `HTTP ${res.status}: ${text.slice(0, 200).replace(/\s+/g, " ").trim()}`;
+            }
+            throw new (ERRORS[res.status] ?? NotefeedError)(message, res.status);
+        }
+        try {
+            const { id, url } = JSON.parse(text);
+            if (typeof id === "string" && typeof url === "string")
+                return { id, url };
+        }
+        catch { }
+        throw new NotefeedError(`unexpected response from ${this.url} (not a notefeed server?)`, res.status);
+    }
+}
+/** Post one note. Options go to Client (url, token, timeoutMs). */
+export function post(markdown, options) {
+    return new Client(options).post(markdown);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { AuthError, Client, ConfigError, InvalidNoteError, NotefeedError, NoteTooLargeError, post } from "./client.js";
+export type { ClientOptions, Note } from "./client.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { AuthError, Client, ConfigError, InvalidNoteError, NotefeedError, NoteTooLargeError, post } from "./client.js";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "notefeed",
+  "version": "0.1.0",
+  "description": "Post markdown notes to a notefeed server, from Node or the command line.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "notefeed": "dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Marceltov/notefeed.git",
+    "directory": "packages/js"
+  },
+  "homepage": "https://marceltov.github.io/notefeed/clients/",
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.9",
+    "vitest": "^4.1"
+  }
+}