notefeed 0.6.0 → 0.8.0

package/README.md

@@ -8,6 +8,8 @@ export NOTEFEED_URL=https://notes.example.com NOTEFEED_FEED=homelab-7f3k2q9x4m8w
 npx notefeed post "# Backup finished"
 backup.sh 2>&1 | npx notefeed post -
 npx notefeed notes --limit 5
+npx notefeed edit 20260929T140512Z-backup-finished "# Backup finished, verified"
+npx notefeed delete 20260929T140512Z-backup-finished
 ```
 
 ```js
@@ -19,6 +21,16 @@ console.log(created.url, created.read_url);
 for await (const note of client.notes()) console.log(note.created_at, note.title); // newest first, page by page
 ```
 
+`read_url` is `null` for a feed without a read link (rare; see the operations docs).
+
 `Client.fromEnv()` reads `NOTEFEED_URL` / `NOTEFEED_FEED` / `NOTEFEED_PASSWORD`; so does the `notefeed` command, unless given `--url` / `--feed` / `--password`.
 
+A feed can have its own password, which gates reading, listing and posting to it. Pass `feedPassword: "..."` to `new Client(...)` (or per call, e.g. `client.post(text, { feedPassword })`), or set `NOTEFEED_FEED_PASSWORD`, which `fromEnv()` and the `notefeed` command both read (there is deliberately no flag, so it stays out of shell history). It is sent as `X-Feed-Password`; `Authorization` stays the instance password. A feed password is 1 to 256 printable ASCII characters with no space at the start or end; an empty one is the same as none.
+
+A posted note can be changed or removed: `await client.edit(id, content)` replaces its content and returns the note (its id and URLs stay), and `await client.delete(id)` removes it. Both take the same `{ feed, feedPassword }` options as `post`, and a missing note is a `NotFoundError`. `notefeed edit <id> <text | - | --file PATH>` prints the note URL; `notefeed delete <id>` prints nothing. Anyone who can post to a feed can edit and delete its notes, and deleting is permanent.
+
+A feed can have a title and a description, and can be deleted: `await client.feedInfo()` returns `{ name, title, description, protected, read_url }`, `await client.updateFeed({ title, description })` replaces both (an empty string clears one) and returns the feed, and `await client.deleteFeed()` removes the feed with all its notes for good. All three take the same `{ feed, feedPassword }` options as `post`, and a feed that doesn't exist is a `NotFoundError`. Anyone who can post to a feed can do this, and deleting is permanent; there are no `notefeed` commands for it.
+
+A picture is a note of its own: `await client.post(bytes, { type: "image/png", alt: "…" })` takes a `Uint8Array` or a `Blob` (PNG, JPEG, GIF or WebP; a Blob's own type is used if you leave `type` out) and returns what a markdown post returns, with the picture's `file` and `file_url` added. Write `![](file)` in a markdown note to show it; the feed is created by its first note, and a picture that is too large is a `NoteTooLargeError`. The server checks the bytes against the declared type. `await client.update(id, { title, alt })` changes a note's title or a picture's alt text, and `await client.edit(id, content)` replaces its content. `await client.updateFeed({ title, description, image: file })` makes a picture the feed's title image (`image: ""` removes it; leaving `image` out keeps it). `notefeed post --file photo.png` posts a file (the type comes from the extension, or `--type`). To post a note with its pictures in one call, `await client.post(text, { attachments: [{ name: "chart.png", content: bytes, type: "image/png" }] })` posts them first and swaps `![](chart.png)` for each file name (`notefeed post "…" --attach chart.png` does the same); a failure carries the pictures already posted as `posted`. Pictures are public to anyone with the feed's read link, and metadata such as EXIF is not removed.
+
 Full documentation: https://docs.notefeed.me/clients/

package/dist/cli.js

@@ -1,14 +1,20 @@
-/** `notefeed post ...` and `notefeed notes ...`: post and read notes from the command line. */
+/** `notefeed post`, `edit`, `update`, `delete` and `notes`: post, change, remove and read notes, markdown or any accepted file, from the command line. */
 import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
 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] [--feed FEED] [--password PASSWORD]",
-    "       notefeed notes [--limit N] [--json] [--url URL] [--feed FEED] [--password PASSWORD]",
+    "usage: notefeed post <text | - | --file PATH> [--type MEDIA_TYPE] [--title TITLE] [--tag TAG]... [--attach PATH]... [--url URL] [--feed FEED] [--password PASSWORD]",
+    "       notefeed edit <id> <text | - | --file PATH> [--type MEDIA_TYPE] [--url URL] [--feed FEED] [--password PASSWORD]",
+    "       notefeed update <id> [--title TITLE] [--alt ALT] [--url URL] [--feed FEED] [--password PASSWORD]",
+    "       notefeed delete <id> [--url URL] [--feed FEED] [--password PASSWORD]",
+    "       notefeed notes [--limit N] [--tag TAG] [--json] [--url URL] [--feed FEED] [--password PASSWORD]",
 ].join("\n");
+// The media type of a file by its extension: the types the server accepts.
+const TYPES = { ".md": "text/markdown", ".markdown": "text/markdown", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" };
 /** Returns the exit code: 0 ok, 1 server/network error, 2 usage/config error. */
 export async function main(argv, io = process) {
     try {
@@ -20,6 +26,11 @@ export async function main(argv, io = process) {
                 feed: { type: "string" },
                 password: { type: "string" },
                 file: { type: "string" },
+                type: { type: "string" },
+                title: { type: "string" },
+                alt: { type: "string" },
+                tag: { type: "string", multiple: true },
+                attach: { type: "string", multiple: true },
                 limit: { type: "string" },
                 json: { type: "boolean" },
                 version: { type: "boolean" },
@@ -37,21 +48,39 @@ export async function main(argv, io = process) {
         }
         const [command, text, ...rest] = positionals;
         if (command === "post" && !rest.length) {
-            const markdown = await read(text, values.file, io);
-            const note = await client(values).post(markdown);
+            const input = await read(text, values.file, values.type, io);
+            const attachments = await Promise.all((values.attach ?? []).map(attachment));
+            const note = await client(values).post(input.content, { type: input.type, title: values.title, tags: values.tag, name: input.name, attachments });
+            io.stdout.write(`${[note.url, ...note.attachments.map((a) => a.url)].join("\n")}\n`);
+            return 0;
+        }
+        if (command === "edit" && text !== undefined && rest.length <= 1) {
+            const input = await read(rest[0], values.file, values.type, io);
+            const note = await client(values).edit(text, input.content, { type: input.type });
             io.stdout.write(`${note.url}\n`);
             return 0;
         }
+        if (command === "update" && text !== undefined && !rest.length) {
+            if (values.title === undefined && values.alt === undefined)
+                throw new UsageError("give --title and/or --alt");
+            const note = await client(values).update(text, { title: values.title, alt: values.alt });
+            io.stdout.write(`${note.url}\n`);
+            return 0;
+        }
+        if (command === "delete" && text !== undefined && !rest.length) {
+            await client(values).delete(text);
+            return 0;
+        }
         if (command === "notes" && text === undefined) {
             const limit = Number(values.limit ?? 20);
             if (!Number.isInteger(limit) || limit < 1)
                 throw new UsageError("--limit must be a whole number, 1 or more");
             let left = limit;
-            for await (const n of client(values).notes({ pageSize: Math.min(limit, 100) })) {
+            for await (const n of client(values).notes({ pageSize: Math.min(limit, 100), tag: values.tag?.[0] })) {
                 // To the second, UTC: the same form as the Python CLI, so scripts read either the same way.
                 const when = new Date(n.created_at).toISOString().replace(/\.\d+Z$/, "Z");
                 // --json: exactly the documented fields, like the Python CLI, even if the server adds more.
-                const fields = { id: n.id, title: n.title, markdown: n.markdown, created_at: when, url: n.url };
+                const fields = { id: n.id, type: n.type, title: n.title, ...(n.content !== undefined && { content: n.content }), file: n.file, file_url: n.file_url, size: n.size, tags: n.tags, created_at: when, url: n.url };
                 io.stdout.write(values.json ? `${JSON.stringify(fields)}\n` : `${when}  ${n.title || n.id}  ${n.url}\n`);
                 if (--left === 0)
                     break;
@@ -62,6 +91,9 @@ export async function main(argv, io = process) {
     }
     catch (e) {
         io.stderr.write(`notefeed: ${e.message.split("\n")[0]}\n`);
+        if (e instanceof NotefeedError)
+            for (const p of e.posted)
+                io.stderr.write(`posted: ${p.url}\n`);
         if (e instanceof ConfigError || e instanceof UsageError)
             return 2;
         if (e instanceof NotefeedError)
@@ -69,7 +101,7 @@ export async function main(argv, io = process) {
         return 2; // parseArgs rejects unknown options with a TypeError
     }
 }
-// Flags win over NOTEFEED_URL, NOTEFEED_FEED and NOTEFEED_PASSWORD.
+// Flags win over NOTEFEED_URL, NOTEFEED_FEED and NOTEFEED_PASSWORD. NOTEFEED_FEED_PASSWORD has no flag: it would end up in shell history.
 function client(values) {
     const url = values.url || process.env.NOTEFEED_URL;
     const feed = values.feed || process.env.NOTEFEED_FEED;
@@ -77,28 +109,52 @@ function client(values) {
         throw new UsageError("no URL given; pass --url or set NOTEFEED_URL");
     if (!feed)
         throw new UsageError("no feed given; pass --feed or set NOTEFEED_FEED");
-    return new Client({ url, feed, password: values.password || process.env.NOTEFEED_PASSWORD });
+    return new Client({
+        url,
+        feed,
+        password: values.password || process.env.NOTEFEED_PASSWORD,
+        feedPassword: process.env.NOTEFEED_FEED_PASSWORD,
+    });
 }
-async function read(text, file, io) {
+// What a post or an edit sends: text on the command line or stdin is markdown; a file is sent as it is, as `--type` or its extension says.
+async function read(text, file, type, io) {
     if (file) {
+        const media = type ?? TYPES[extname(file).toLowerCase()];
+        if (!media)
+            throw new UsageError(`cannot tell the type of ${file}: pass --type (${Object.values(TYPES).filter((t, i, a) => a.indexOf(t) === i).join(", ")})`);
+        let bytes;
         try {
-            return utf8(await readFile(file), file);
+            bytes = await readFile(file);
         }
         catch (e) {
-            if (e instanceof UsageError)
-                throw e;
             throw new UsageError(`cannot read ${file}: ${e.code ?? e.message}`);
         }
+        return { content: media === "text/markdown" ? utf8(bytes, file) : bytes, type: media, name: basename(file) };
     }
     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");
+        return { content: utf8(Buffer.concat(chunks), "stdin"), type: type ?? "text/markdown" };
     }
     if (text === undefined)
         throw new UsageError('give the note text, "-" for stdin, or --file PATH');
-    return text;
+    return { content: text, type: type ?? "text/markdown" };
+}
+// A picture to post first: its name is the file's, its type comes from the extension.
+async function attachment(path) {
+    const type = TYPES[extname(path).toLowerCase()];
+    if (!type || type === "text/markdown")
+        throw new UsageError(`cannot attach ${path}: a picture (${Object.keys(TYPES).filter((e) => TYPES[e] !== "text/markdown").join(", ")}) is expected`);
+    const name = basename(path);
+    if (!/^(?!\.+$)[A-Za-z0-9._-]+$/.test(name))
+        throw new UsageError(`cannot attach ${path}: its file name "${name}" is what the text refers to it by, so it may only have letters, digits, ., _ and -: rename the file`);
+    try {
+        return { name, content: await readFile(path), type };
+    }
+    catch (e) {
+        throw new UsageError(`cannot read ${path}: ${e.code ?? e.message}`);
+    }
 }
 function utf8(bytes, source) {
     try {

package/dist/client.d.ts

@@ -1,12 +1,20 @@
-import type { Created, Error as ApiError, Note } from "./generated/types.gen.js";
+import type { Created, Error as ApiError, Feed, FeedSettings, Note } from "./generated/types.gen.js";
 /** The stable error codes the API answers with. */
 export type ErrorCode = NonNullable<ApiError["code"]>;
-export type { Created, Note };
+export type { Created, Feed, FeedSettings, Note };
+/** A picture posted with a note: `![](name)` in the markdown refers to it. `type` as for post(). */
+export type Attachment = {
+    name: string;
+    content: Uint8Array | Blob;
+    type?: string;
+    alt?: string;
+};
 /** `timeoutMs` (default 10000) limits each whole request, including reading the answer. */
 export type ClientOptions = {
     url: string;
     feed?: string;
     password?: string;
+    feedPassword?: string;
     timeoutMs?: number;
 };
 /** Any failure talking to notefeed. `status` and `code` are null when there was no API answer. */
@@ -14,6 +22,9 @@ export declare class NotefeedError extends Error {
     readonly status: number | null;
     readonly code: ErrorCode | null;
     constructor(message: string, status?: number | null, code?: ErrorCode | null);
+    /** Set when a post with `attachments` failed on one of them: its name, and the images already posted (the text note is not). */
+    attachment: string | null;
+    posted: Created[];
 }
 /** Raised before sending: no URL, no feed, an invalid feed name or password. */
 export declare class ConfigError extends NotefeedError {
@@ -29,10 +40,10 @@ export declare class RateLimitedError extends NotefeedError {
 /** No such note, or a malformed read id. */
 export declare class NotFoundError extends NotefeedError {
 }
-/** The instance's feed or note limit is reached. */
+/** The instance's feed or note limit, or the feed's image limit, is reached. */
 export declare class LimitReachedError extends NotefeedError {
 }
-/** The note is over the server's size limit. */
+/** The note or image is over the server's size limit. */
 export declare class NoteTooLargeError extends NotefeedError {
 }
 /** The server refused the request itself: invalid or reserved feed, empty note, bad body or parameter. */
@@ -43,24 +54,90 @@ export declare class Client {
     readonly feed: string | null;
     private readonly api;
     private readonly timeoutMs;
+    private readonly feedPassword;
     /** A notefeed server. The feed set here is the default for every call; each call can override it. */
     constructor(options: ClientOptions);
-    /** NOTEFEED_URL, NOTEFEED_FEED and NOTEFEED_PASSWORD. */
+    /** NOTEFEED_URL, NOTEFEED_FEED, NOTEFEED_PASSWORD and NOTEFEED_FEED_PASSWORD. */
     static fromEnv(env?: Record<string, string | undefined>): Client;
-    post(markdown: string, options?: {
+    /**
+     * Post a note: a string is markdown, bytes or a Blob are a file whose media type is `type` (a Blob's own `type` if left out): `text/markdown`,
+     * `image/png`, `image/jpeg`, `image/gif` or `image/webp`. The server accepts nothing else and checks that the body is what the type says.
+     * The feed is created by its first note. `Created.file` is the note's file name: write `![](file)` in a markdown note to show a picture, or
+     * pass it as `image` to updateFeed; `file_url` is for a link outside notefeed.
+     *
+     * `feedPassword` overrides the client's, for a feed that has its own password. `tags` label the note (at most 10, each 1 to 32 characters of
+     * letters, digits, `-`, `_`, `.`, `:`; not verified). `title` is its title (at most 100 characters, one line); left out, it is taken from the
+     * text. `alt` is a picture's alternative text, `name` the file's original name. `readId` is the read id the feed gets when this post creates it
+     * (3 to 64 characters of `a-z`, `0-9`, `-`, `_`; random when left out; ignored for a feed that exists; a `taken` error when another feed has it).
+     *
+     * `attachments` (only with a markdown string) are pictures posted first, one note each, in order: `![](name)` in the markdown shows one (an
+     * attachment the text never refers to is added at the end), and `Created.attachments` lists them. `tags` label the images too. The options
+     * are checked before anything is sent. If an upload fails, its error is thrown with `attachment` (the name) and `posted` (the images already
+     * posted, which stay) set; the text note is not posted.
+     */
+    post(content: string | Uint8Array | Blob, options?: {
+        feed?: string;
+        feedPassword?: string;
+        type?: string;
+        title?: string;
+        tags?: string[];
+        alt?: string;
+        name?: string;
+        readId?: string;
+        attachments?: Attachment[];
+    }): Promise<Created & {
+        attachments: Created[];
+    }>;
+    private postOne;
+    /** Replace a note's content (a string is markdown; bytes and Blobs need the note's own `type`, as for post()). Its id, URLs and metadata stay. Same options as post(). */
+    edit(id: string, content: string | Uint8Array | Blob, options?: {
+        feed?: string;
+        feedPassword?: string;
+        type?: string;
+    }): Promise<Note>;
+    /** Set a note's title and/or alt text (alt for pictures); `""` removes one, so a markdown note's title follows its text again. Same options as post(). */
+    update(id: string, meta: {
+        title?: string;
+        alt?: string;
+    }, options?: {
+        feed?: string;
+        feedPassword?: string;
+    }): Promise<Note>;
+    /** Remove a note for good. The feed stays, even with no notes left. Same options as post(). */
+    delete(id: string, options?: {
+        feed?: string;
+        feedPassword?: string;
+    }): Promise<void>;
+    /** The feed's name, title, description, whether it has a password, and its read link (null while it has no notes). Same options as post(). */
+    feedInfo(options?: {
+        feed?: string;
+        feedPassword?: string;
+    }): Promise<Feed>;
+    /** Replace the feed's title and description (both; an empty string clears one), and set (`image`: a file name from uploadImage) or clear (`""`) the title image; leave `image` out to keep it. `read_id` gives the feed another read id (3 to 64 characters of `a-z`, `0-9`, `-`, `_`; `""` for a random one; left out keeps it); the old one is freed, and relative image links in notes follow while full URLs do not. The feed must already exist. Same options as post(). */
+    updateFeed(settings: FeedSettings, options?: {
+        feed?: string;
+        feedPassword?: string;
+    }): Promise<Feed>;
+    /** Delete the feed with all its notes, settings and password, for good; its name is free again. Same options as post(). */
+    deleteFeed(options?: {
         feed?: string;
-    }): Promise<Created>;
-    /** Every note in the feed, newest first, fetched a page at a time; stop iterating whenever you like. */
+        feedPassword?: string;
+    }): Promise<void>;
+    /** Every note in the feed, newest first, fetched a page at a time; stop iterating whenever you like. `tag`: only notes carrying it. */
     notes(options?: {
         feed?: string;
+        feedPassword?: string;
         pageSize?: number;
+        tag?: string;
     }): AsyncGenerator<Note>;
     note(id: string, options?: {
         feed?: string;
+        feedPassword?: string;
     }): Promise<Note>;
     /** Like notes(), by the feed's read id: public, read-only, needs no password. */
     readNotes(readId: string, options?: {
         pageSize?: number;
+        tag?: string;
     }): AsyncGenerator<Note>;
     readNote(readId: string, id: string): Promise<Note>;
     private feedFor;

package/dist/client.js

@@ -3,7 +3,7 @@
  * OpenAPI description (./generated, `npm run generate` in the repo). No runtime dependencies.
  */
 import { createClient, createConfig } from "./generated/client/index.js";
-import { getNote, getReadNote, listNotes, listReadNotes, postNote } from "./generated/sdk.gen.js";
+import { deleteFeed, deleteNote, editNote, getFeed, getNote, getReadNote, listNotes, listReadNotes, patchNote, postNote, updateFeed } from "./generated/sdk.gen.js";
 /** Any failure talking to notefeed. `status` and `code` are null when there was no API answer. */
 export class NotefeedError extends Error {
     status;
@@ -14,6 +14,9 @@ export class NotefeedError extends Error {
         this.code = code;
         this.name = new.target.name;
     }
+    /** Set when a post with `attachments` failed on one of them: its name, and the images already posted (the text note is not). */
+    attachment = null;
+    posted = [];
 }
 /** Raised before sending: no URL, no feed, an invalid feed name or password. */
 export class ConfigError extends NotefeedError {
@@ -32,10 +35,10 @@ export class RateLimitedError extends NotefeedError {
 /** No such note, or a malformed read id. */
 export class NotFoundError extends NotefeedError {
 }
-/** The instance's feed or note limit is reached. */
+/** The instance's feed or note limit, or the feed's image limit, is reached. */
 export class LimitReachedError extends NotefeedError {
 }
-/** The note is over the server's size limit. */
+/** The note or image is over the server's size limit. */
 export class NoteTooLargeError extends NotefeedError {
 }
 /** The server refused the request itself: invalid or reserved feed, empty note, bad body or parameter. */
@@ -46,23 +49,53 @@ const BY_CODE = {
     not_found: NotFoundError,
     feed_limit: LimitReachedError,
     note_limit: LimitReachedError,
+    image_limit: LimitReachedError,
     too_large: NoteTooLargeError,
     invalid_feed: InvalidRequestError,
     reserved_feed: InvalidRequestError,
     empty_note: InvalidRequestError,
     invalid_body: InvalidRequestError,
     invalid_request: InvalidRequestError,
+    feed_exists: InvalidRequestError,
+    taken: InvalidRequestError,
     unsupported_type: InvalidRequestError,
 };
+const ATTACHMENT_NAME = /^(?!\.+$)[A-Za-z0-9._-]+$/; // same rule as the server's MCP tool: safe to write in ![](name)
+const IMAGE_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
 const FEED_RE = /^[a-z0-9_-]{1,64}$/; // same rule as the server; reserved names still come back as a 400
+// A header holds bytes, and fetch refuses a character above U+00FF: text that may not be ASCII goes as its UTF-8 bytes written as
+// latin1 characters, which is what the server reads back.
+const headerValue = (text) => Array.from(new TextEncoder().encode(text), (b) => String.fromCharCode(b)).join("");
+// What a post sends: a string is markdown; bytes and Blobs need a media type (a Blob's own, if it has one).
+function asFile(content, type) {
+    if (typeof content === "string")
+        return { body: new Blob([content]), type: type ?? "text/markdown" };
+    const media = type ?? (content instanceof Blob ? content.type : "");
+    if (!media)
+        throw new ConfigError("give the file's media type as `type`, e.g. image/png");
+    return { body: content instanceof Blob ? content : new Blob([content]), type: media };
+}
+// The markdown with each `![](name)` of `sent` (name → file) pointing at its file; a name the text never refers to is appended as `![](file)`.
+function placeImages(markdown, sent) {
+    const used = new Set();
+    const text = markdown.replace(/(!\[[^\]]*\]\()([^)\s]+)(\))/g, (m, head, dest, tail) => {
+        if (!sent.has(dest))
+            return m;
+        used.add(dest);
+        return head + sent.get(dest) + tail;
+    });
+    const rest = [...sent].filter(([name]) => !used.has(name)).map(([, file]) => `![](${file})`);
+    return rest.length === 0 ? text : [text.trimEnd(), ...rest].filter((p) => p !== "").join("\n\n");
+}
 export class Client {
     url;
     feed;
     api;
     timeoutMs;
+    feedPassword;
     /** A notefeed server. The feed set here is the default for every call; each call can override it. */
     constructor(options) {
-        const { url, feed, password, timeoutMs } = options ?? {};
+        const { url, feed, password, feedPassword, timeoutMs } = options ?? {};
         if (!url)
             throw new ConfigError("no url given");
         this.url = url.replace(/\/+$/, "");
@@ -71,29 +104,139 @@ export class Client {
         // Never echo the value: it would end up in terminals and CI logs.
         if (pw && /[\x00-\x1f\x7f]/.test(pw))
             throw new ConfigError("password contains invalid characters");
+        this.feedPassword = checkFeedPassword(feedPassword);
         this.timeoutMs = timeoutMs ?? 10_000;
         this.api = createClient(createConfig({ baseUrl: this.url, headers: pw ? { Authorization: `Bearer ${pw}` } : {} }));
     }
-    /** NOTEFEED_URL, NOTEFEED_FEED and NOTEFEED_PASSWORD. */
+    /** NOTEFEED_URL, NOTEFEED_FEED, NOTEFEED_PASSWORD and NOTEFEED_FEED_PASSWORD. */
     static fromEnv(env = process.env) {
-        return new Client({ url: env.NOTEFEED_URL ?? "", feed: env.NOTEFEED_FEED || undefined, password: env.NOTEFEED_PASSWORD });
+        return new Client({
+            url: env.NOTEFEED_URL ?? "",
+            feed: env.NOTEFEED_FEED || undefined,
+            password: env.NOTEFEED_PASSWORD,
+            feedPassword: env.NOTEFEED_FEED_PASSWORD,
+        });
+    }
+    /**
+     * Post a note: a string is markdown, bytes or a Blob are a file whose media type is `type` (a Blob's own `type` if left out): `text/markdown`,
+     * `image/png`, `image/jpeg`, `image/gif` or `image/webp`. The server accepts nothing else and checks that the body is what the type says.
+     * The feed is created by its first note. `Created.file` is the note's file name: write `![](file)` in a markdown note to show a picture, or
+     * pass it as `image` to updateFeed; `file_url` is for a link outside notefeed.
+     *
+     * `feedPassword` overrides the client's, for a feed that has its own password. `tags` label the note (at most 10, each 1 to 32 characters of
+     * letters, digits, `-`, `_`, `.`, `:`; not verified). `title` is its title (at most 100 characters, one line); left out, it is taken from the
+     * text. `alt` is a picture's alternative text, `name` the file's original name. `readId` is the read id the feed gets when this post creates it
+     * (3 to 64 characters of `a-z`, `0-9`, `-`, `_`; random when left out; ignored for a feed that exists; a `taken` error when another feed has it).
+     *
+     * `attachments` (only with a markdown string) are pictures posted first, one note each, in order: `![](name)` in the markdown shows one (an
+     * attachment the text never refers to is added at the end), and `Created.attachments` lists them. `tags` label the images too. The options
+     * are checked before anything is sent. If an upload fails, its error is thrown with `attachment` (the name) and `posted` (the images already
+     * posted, which stay) set; the text note is not posted.
+     */
+    async post(content, options = {}) {
+        const { attachments = [], ...own } = options;
+        if (attachments.length === 0)
+            return { ...(await this.postOne(content, own)), attachments: [] };
+        if (typeof content !== "string")
+            throw new ConfigError("attachments go with a markdown string");
+        if ((own.type ?? "text/markdown") !== "text/markdown")
+            throw new ConfigError("attachments go with a markdown string");
+        const types = attachments.map((a) => {
+            if (!ATTACHMENT_NAME.test(a.name))
+                throw new ConfigError(`attachment name "${a.name}": use letters, digits, ., _ and - only`);
+            const type = asFile(a.content, a.type).type;
+            if (!IMAGE_TYPES.includes(type))
+                throw new ConfigError(`attachment "${a.name}" must be a picture (${IMAGE_TYPES.join(", ")})`);
+            return type;
+        });
+        const dup = attachments.find((a, i) => attachments.findIndex((b) => b.name === a.name) !== i);
+        if (dup)
+            throw new ConfigError(`attachment "${dup.name}" is given twice`);
+        const posted = [];
+        const sent = new Map();
+        for (const [i, a] of attachments.entries()) {
+            try {
+                const done = await this.postOne(a.content, { feed: own.feed, feedPassword: own.feedPassword, type: types[i], alt: a.alt, name: a.name, tags: own.tags, readId: own.readId });
+                posted.push(done);
+                sent.set(a.name, done.file);
+            }
+            catch (e) {
+                if (e instanceof NotefeedError) {
+                    e.message = `attachment "${a.name}": ${e.message}`;
+                    e.attachment = a.name;
+                    e.posted = posted;
+                }
+                throw e;
+            }
+        }
+        try {
+            return { ...(await this.postOne(placeImages(content, sent), own)), attachments: posted };
+        }
+        catch (e) {
+            if (e instanceof NotefeedError)
+                e.posted = posted; // the text failed: the images stay, `attachment` stays null
+            throw e;
+        }
+    }
+    async postOne(content, options) {
+        const feed = this.feedFor(options.feed);
+        const { body, type } = asFile(content, options.type);
+        const headers = {
+            ...this.opts(options.feedPassword).headers,
+            "Content-Type": type,
+            ...(options.title && { "X-Note-Title": headerValue(options.title) }),
+            ...(options.tags?.length && { "X-Note-Tags": options.tags.join(",") }),
+            ...(options.alt && { "X-Note-Alt": headerValue(options.alt) }),
+            ...(options.name && { "X-Note-Name": headerValue(options.name) }),
+            ...(options.readId && { "X-Read-Id": options.readId }),
+        };
+        return this.call(postNote({ client: this.api, path: { feed }, body, headers, signal: AbortSignal.timeout(this.timeoutMs) }));
+    }
+    /** Replace a note's content (a string is markdown; bytes and Blobs need the note's own `type`, as for post()). Its id, URLs and metadata stay. Same options as post(). */
+    async edit(id, content, options = {}) {
+        const feed = this.feedFor(options.feed);
+        const { body, type } = asFile(content, options.type);
+        const headers = { ...this.opts(options.feedPassword).headers, "Content-Type": type };
+        return this.call(editNote({ client: this.api, path: { feed, id }, body, headers, signal: AbortSignal.timeout(this.timeoutMs) }));
     }
-    async post(markdown, options = {}) {
+    /** Set a note's title and/or alt text (alt for pictures); `""` removes one, so a markdown note's title follows its text again. Same options as post(). */
+    async update(id, meta, options = {}) {
         const feed = this.feedFor(options.feed);
-        return this.call(postNote({ client: this.api, path: { feed }, body: { markdown }, ...this.opts() }));
+        return this.call(patchNote({ client: this.api, path: { feed, id }, body: meta, ...this.opts(options.feedPassword) }));
     }
-    /** Every note in the feed, newest first, fetched a page at a time; stop iterating whenever you like. */
+    /** Remove a note for good. The feed stays, even with no notes left. Same options as post(). */
+    async delete(id, options = {}) {
+        const feed = this.feedFor(options.feed);
+        await this.call(deleteNote({ client: this.api, path: { feed, id }, ...this.opts(options.feedPassword) }));
+    }
+    /** The feed's name, title, description, whether it has a password, and its read link (null while it has no notes). Same options as post(). */
+    async feedInfo(options = {}) {
+        const feed = this.feedFor(options.feed);
+        return this.call(getFeed({ client: this.api, path: { feed }, ...this.opts(options.feedPassword) }));
+    }
+    /** Replace the feed's title and description (both; an empty string clears one), and set (`image`: a file name from uploadImage) or clear (`""`) the title image; leave `image` out to keep it. `read_id` gives the feed another read id (3 to 64 characters of `a-z`, `0-9`, `-`, `_`; `""` for a random one; left out keeps it); the old one is freed, and relative image links in notes follow while full URLs do not. The feed must already exist. Same options as post(). */
+    async updateFeed(settings, options = {}) {
+        const feed = this.feedFor(options.feed);
+        const body = { title: settings.title, description: settings.description, ...(settings.image === undefined ? {} : { image: settings.image }), ...(settings.read_id === undefined ? {} : { read_id: settings.read_id }) };
+        return this.call(updateFeed({ client: this.api, path: { feed }, body, ...this.opts(options.feedPassword) }));
+    }
+    /** Delete the feed with all its notes, settings and password, for good; its name is free again. Same options as post(). */
+    async deleteFeed(options = {}) {
+        const feed = this.feedFor(options.feed);
+        await this.call(deleteFeed({ client: this.api, path: { feed }, ...this.opts(options.feedPassword) }));
+    }
+    /** Every note in the feed, newest first, fetched a page at a time; stop iterating whenever you like. `tag`: only notes carrying it. */
     notes(options = {}) {
         const feed = this.feedFor(options.feed);
-        return this.pages((before) => listNotes({ client: this.api, path: { feed }, query: { limit: options.pageSize, before }, ...this.opts() }));
+        return this.pages((before) => listNotes({ client: this.api, path: { feed }, query: { limit: options.pageSize, before, tag: options.tag }, ...this.opts(options.feedPassword) }));
     }
     async note(id, options = {}) {
         const feed = this.feedFor(options.feed);
-        return this.call(getNote({ client: this.api, path: { feed, id }, ...this.opts() }));
+        return this.call(getNote({ client: this.api, path: { feed, id }, ...this.opts(options.feedPassword) }));
     }
     /** Like notes(), by the feed's read id: public, read-only, needs no password. */
     readNotes(readId, options = {}) {
-        return this.pages((before) => listReadNotes({ client: this.api, path: { readId }, query: { limit: options.pageSize, before }, ...this.opts() }));
+        return this.pages((before) => listReadNotes({ client: this.api, path: { readId }, query: { limit: options.pageSize, before, tag: options.tag }, ...this.opts() }));
     }
     async readNote(readId, id) {
         return this.call(getReadNote({ client: this.api, path: { readId, id }, ...this.opts() }));
@@ -104,8 +247,9 @@ export class Client {
             throw new ConfigError("no feed given");
         return checkFeed(f);
     }
-    opts() {
-        return { signal: AbortSignal.timeout(this.timeoutMs) };
+    opts(feedPassword) {
+        const fp = checkFeedPassword(feedPassword) ?? this.feedPassword;
+        return { signal: AbortSignal.timeout(this.timeoutMs), headers: fp ? { "X-Feed-Password": fp } : {} };
     }
     // `before` is the previous page's `next`: older notes only, so notes posted meanwhile never repeat.
     async *pages(fetchPage) {
@@ -128,6 +272,8 @@ export class Client {
         if (response.redirected) {
             throw new NotefeedError(`${this.url} redirected to ${new URL(response.url).origin}: use that address as the URL`, response.status);
         }
+        if (response.status === 204 && error === undefined)
+            return undefined; // delete: no body
         if (response.ok) {
             if (error === undefined && isObject(data))
                 return data;
@@ -155,3 +301,10 @@ function checkFeed(feed) {
         throw new ConfigError("invalid feed name: use 1-64 of a-z, 0-9, _ and -");
     return feed;
 }
+function checkFeedPassword(value) {
+    const v = value?.trim() || null;
+    // Never echo the value: it would end up in terminals and CI logs.
+    if (v && /[\x00-\x1f\x7f]/.test(v))
+        throw new ConfigError("feed password contains invalid characters");
+    return v;
+}

package/dist/generated/index.d.ts

@@ -1,2 +1,2 @@
-export { getNote, getOpenApi, getReadNote, listNotes, listReadNotes, type Options, postNote } from './sdk.gen.js';
-export type { ClientOptions, Created, Error, GetNoteData, GetNoteError, GetNoteErrors, GetNoteResponse, GetNoteResponses, GetOpenApiData, GetOpenApiResponse, GetOpenApiResponses, GetReadNoteData, GetReadNoteError, GetReadNoteErrors, GetReadNoteResponse, GetReadNoteResponses, ListNotesData, ListNotesError, ListNotesErrors, ListNotesResponse, ListNotesResponses, ListReadNotesData, ListReadNotesError, ListReadNotesErrors, ListReadNotesResponse, ListReadNotesResponses, Note, NoteList, PostForm, PostJson, PostNoteData, PostNoteError, PostNoteErrors, PostNoteResponse, PostNoteResponses } from './types.gen.js';
+export { changeFeedPassword, deleteFeed, deleteNote, editNote, getFeed, getNote, getOpenApi, getReadFeed, getReadNote, listNotes, listReadNotes, type Options, patchNote, postNote, removeFeedPassword, updateFeed } from './sdk.gen.js';
+export type { ChangeFeedPasswordData, ChangeFeedPasswordError, ChangeFeedPasswordErrors, ChangeFeedPasswordResponse, ChangeFeedPasswordResponses, ClientOptions, Created, DeleteFeedData, DeleteFeedError, DeleteFeedErrors, DeleteFeedResponse, DeleteFeedResponses, DeleteNoteData, DeleteNoteError, DeleteNoteErrors, DeleteNoteResponse, DeleteNoteResponses, EditNoteData, EditNoteError, EditNoteErrors, EditNoteResponse, EditNoteResponses, Error, Feed, FeedSettings, GetFeedData, GetFeedError, GetFeedErrors, GetFeedResponse, GetFeedResponses, GetNoteData, GetNoteError, GetNoteErrors, GetNoteResponse, GetNoteResponses, GetOpenApiData, GetOpenApiResponse, GetOpenApiResponses, GetReadFeedData, GetReadFeedError, GetReadFeedErrors, GetReadFeedResponse, GetReadFeedResponses, GetReadNoteData, GetReadNoteError, GetReadNoteErrors, GetReadNoteResponse, GetReadNoteResponses, ListNotesData, ListNotesError, ListNotesErrors, ListNotesResponse, ListNotesResponses, ListReadNotesData, ListReadNotesError, ListReadNotesErrors, ListReadNotesResponse, ListReadNotesResponses, Note, NoteList, NoteMeta, PasswordJson, PatchNoteData, PatchNoteError, PatchNoteErrors, PatchNoteResponse, PatchNoteResponses, PostNoteData, PostNoteError, PostNoteErrors, PostNoteResponse, PostNoteResponses, ReadFeed, RemoveFeedPasswordData, RemoveFeedPasswordError, RemoveFeedPasswordErrors, RemoveFeedPasswordResponse, RemoveFeedPasswordResponses, UpdateFeedData, UpdateFeedError, UpdateFeedErrors, UpdateFeedResponse, UpdateFeedResponses } from './types.gen.js';

package/dist/generated/index.js

@@ -1,2 +1,2 @@
 // This file is auto-generated by @hey-api/openapi-ts
-export { getNote, getOpenApi, getReadNote, listNotes, listReadNotes, postNote } from './sdk.gen.js';
+export { changeFeedPassword, deleteFeed, deleteNote, editNote, getFeed, getNote, getOpenApi, getReadFeed, getReadNote, listNotes, listReadNotes, patchNote, postNote, removeFeedPassword, updateFeed } from './sdk.gen.js';