notefeed 0.7.0 → 0.8.0

package/README.md

@@ -27,10 +27,10 @@ for await (const note of client.notes()) console.log(note.created_at, note.title
 
 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, markdown)` replaces its text 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 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.
 
-An image can be uploaded to an existing feed and then used in a note: `const { file, url, markdown } = await client.uploadImage(bytes)` takes a `Uint8Array` or a `Blob` (PNG, JPEG, GIF or WebP; the server recognizes the format by the bytes), takes the same `{ feed, feedPassword }` options as `post`, and returns the image's `url` and `markdown` (`![](url)`), which you put in a note. The feed must already have a note, and an image that is too large is a `NoteTooLargeError`. `await client.updateFeed({ title, description, image: file })` makes an uploaded image the feed's title image (`image: ""` removes it; leaving `image` out keeps it). `notefeed image <PATH>` uploads a file and prints the markdown. Images are public to anyone with the feed's read link, and metadata such as EXIF is not removed.
+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,17 +1,20 @@
-/** `notefeed post`, `edit`, `delete`, `notes` and `image`: post, change, remove and read notes, and upload images, 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> [--tag TAG]... [--url URL] [--feed FEED] [--password PASSWORD]",
-    "       notefeed edit <id> <text | - | --file PATH> [--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 image <PATH> [--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 {
@@ -23,7 +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" },
@@ -41,29 +48,27 @@ 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, { tags: values.tag });
-            io.stdout.write(`${note.url}\n`);
+            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 note = await client(values).edit(text, await read(rest[0], values.file, io));
+            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 === "delete" && text !== undefined && !rest.length) {
-            await client(values).delete(text);
+        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 === "image" && text !== undefined && !rest.length) {
-            let bytes;
-            try {
-                bytes = await readFile(text);
-            }
-            catch (e) {
-                throw new UsageError(`cannot read ${text}: ${e.code ?? e.message}`);
-            }
-            io.stdout.write(`${(await client(values).uploadImage(bytes)).markdown}\n`);
+        if (command === "delete" && text !== undefined && !rest.length) {
+            await client(values).delete(text);
             return 0;
         }
         if (command === "notes" && text === undefined) {
@@ -75,7 +80,7 @@ export async function main(argv, io = process) {
                 // 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;
@@ -86,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)
@@ -108,26 +116,45 @@ function client(values) {
         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,7 +1,14 @@
-import type { Created, Error as ApiError, Feed, FeedSettings, ImageUploaded, 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, Feed, FeedSettings, ImageUploaded, 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;
@@ -15,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 {
@@ -49,19 +59,47 @@ export declare class Client {
     constructor(options: ClientOptions);
     /** NOTEFEED_URL, NOTEFEED_FEED, NOTEFEED_PASSWORD and NOTEFEED_FEED_PASSWORD. */
     static fromEnv(env?: Record<string, string | undefined>): Client;
-    /** `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). */
-    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[];
-    }): Promise<Created>;
-    /** Upload a PNG, JPEG, GIF or WebP image to an existing feed. The server decides the format by the bytes, so no content type is needed. `markdown` in the answer is `![](url)`, to put in a note. Same options as post(). */
-    uploadImage(data: Uint8Array | Blob, options?: {
+        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;
-    }): Promise<ImageUploaded>;
-    /** Replace a note's markdown; its id and URLs stay. Same options as post(). */
-    edit(id: string, markdown: string, options?: {
+        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>;
@@ -75,7 +113,7 @@ export declare class Client {
         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. The feed must already exist. Same options as post(). */
+    /** 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;

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 { deleteFeed, deleteNote, editNote, getFeed, getNote, getReadNote, listNotes, listReadNotes, postNote, updateFeed, uploadImage } 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 {
@@ -54,9 +57,36 @@ const BY_CODE = {
     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;
@@ -87,23 +117,92 @@ export class Client {
             feedPassword: env.NOTEFEED_FEED_PASSWORD,
         });
     }
-    /** `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). */
-    async post(markdown, 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.
+     */
+    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 = { markdown, ...(options.tags?.length && { tags: options.tags }) };
-        return this.call(postNote({ client: this.api, path: { feed }, body, ...this.opts(options.feedPassword) }));
+        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) }));
     }
-    /** Upload a PNG, JPEG, GIF or WebP image to an existing feed. The server decides the format by the bytes, so no content type is needed. `markdown` in the answer is `![](url)`, to put in a note. Same options as post(). */
-    async uploadImage(data, options = {}) {
+    /** 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 = data instanceof Blob ? data : new Blob([data]);
-        const headers = { ...this.opts(options.feedPassword).headers, "Content-Type": "application/octet-stream" };
-        return this.call(uploadImage({ client: this.api, path: { feed }, body, signal: AbortSignal.timeout(this.timeoutMs), headers }));
+        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) }));
     }
-    /** Replace a note's markdown; its id and URLs stay. Same options as post(). */
-    async edit(id, 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(editNote({ client: this.api, path: { feed, id }, body: { markdown }, ...this.opts(options.feedPassword) }));
+        return this.call(patchNote({ client: this.api, path: { feed, id }, body: meta, ...this.opts(options.feedPassword) }));
     }
     /** Remove a note for good. The feed stays, even with no notes left. Same options as post(). */
     async delete(id, options = {}) {
@@ -115,10 +214,10 @@ export class Client {
         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. The feed must already exist. Same options as post(). */
+    /** 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 }) };
+        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(). */

package/dist/generated/index.d.ts

@@ -1,2 +1,2 @@
-export { changeFeedPassword, deleteFeed, deleteNote, editNote, getFeed, getNote, getOpenApi, getReadFeed, getReadNote, listNotes, listReadNotes, type Options, postNote, removeFeedPassword, updateFeed, uploadImage } 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, ImageUploaded, ListNotesData, ListNotesError, ListNotesErrors, ListNotesResponse, ListNotesResponses, ListReadNotesData, ListReadNotesError, ListReadNotesErrors, ListReadNotesResponse, ListReadNotesResponses, Note, NoteList, PasswordJson, PostForm, PostJson, PostNoteData, PostNoteError, PostNoteErrors, PostNoteResponse, PostNoteResponses, ReadFeed, RemoveFeedPasswordData, RemoveFeedPasswordError, RemoveFeedPasswordErrors, RemoveFeedPasswordResponse, RemoveFeedPasswordResponses, UpdateFeedData, UpdateFeedError, UpdateFeedErrors, UpdateFeedResponse, UpdateFeedResponses, UploadImageData, UploadImageError, UploadImageErrors, UploadImageResponse, UploadImageResponses } 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 { changeFeedPassword, deleteFeed, deleteNote, editNote, getFeed, getNote, getOpenApi, getReadFeed, getReadNote, listNotes, listReadNotes, postNote, removeFeedPassword, updateFeed, uploadImage } from './sdk.gen.js';
+export { changeFeedPassword, deleteFeed, deleteNote, editNote, getFeed, getNote, getOpenApi, getReadFeed, getReadNote, listNotes, listReadNotes, patchNote, postNote, removeFeedPassword, updateFeed } from './sdk.gen.js';

package/dist/generated/sdk.gen.d.ts

@@ -1,5 +1,5 @@
 import type { Client, ClientMeta, Options as Options2, RequestResult, TDataShape } from './client/index.js';
-import type { ChangeFeedPasswordData, ChangeFeedPasswordErrors, ChangeFeedPasswordResponses, DeleteFeedData, DeleteFeedErrors, DeleteFeedResponses, DeleteNoteData, DeleteNoteErrors, DeleteNoteResponses, EditNoteData, EditNoteErrors, EditNoteResponses, GetFeedData, GetFeedErrors, GetFeedResponses, GetNoteData, GetNoteErrors, GetNoteResponses, GetOpenApiData, GetOpenApiResponses, GetReadFeedData, GetReadFeedErrors, GetReadFeedResponses, GetReadNoteData, GetReadNoteErrors, GetReadNoteResponses, ListNotesData, ListNotesErrors, ListNotesResponses, ListReadNotesData, ListReadNotesErrors, ListReadNotesResponses, PostNoteData, PostNoteErrors, PostNoteResponses, RemoveFeedPasswordData, RemoveFeedPasswordErrors, RemoveFeedPasswordResponses, UpdateFeedData, UpdateFeedErrors, UpdateFeedResponses, UploadImageData, UploadImageErrors, UploadImageResponses } from './types.gen.js';
+import type { ChangeFeedPasswordData, ChangeFeedPasswordErrors, ChangeFeedPasswordResponses, DeleteFeedData, DeleteFeedErrors, DeleteFeedResponses, DeleteNoteData, DeleteNoteErrors, DeleteNoteResponses, EditNoteData, EditNoteErrors, EditNoteResponses, GetFeedData, GetFeedErrors, GetFeedResponses, GetNoteData, GetNoteErrors, GetNoteResponses, GetOpenApiData, GetOpenApiResponses, GetReadFeedData, GetReadFeedErrors, GetReadFeedResponses, GetReadNoteData, GetReadNoteErrors, GetReadNoteResponses, ListNotesData, ListNotesErrors, ListNotesResponses, ListReadNotesData, ListReadNotesErrors, ListReadNotesResponses, PatchNoteData, PatchNoteErrors, PatchNoteResponses, PostNoteData, PostNoteErrors, PostNoteResponses, RemoveFeedPasswordData, RemoveFeedPasswordErrors, RemoveFeedPasswordResponses, UpdateFeedData, UpdateFeedErrors, UpdateFeedResponses } from './types.gen.js';
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options2<TData, ThrowOnError, TResponse> & {
     /**
      * You can provide a client instance returned by `createClient()` instead of
@@ -22,7 +22,7 @@ export declare const listNotes: <ThrowOnError extends boolean = false>(options:
 /**
  * Post a note
  *
- * Creates the feed with its first note, optionally protected by its own password (`X-Feed-Password` header or a `password` field in the JSON or form body; 1 to 256 printable ASCII characters, with no space at the start or end). Posting to a protected feed needs that password. Also served at `POST /{feed}`, the short form the client packages and curl one-liners use. The body is at most 102400 bytes and must be UTF-8. `application/x-www-form-urlencoded` (what `curl -d` sends) is read as raw markdown, not as form fields. Tags (at most 10 tags, each 1 to 32 characters of letters, digits, `-`, `_`, `.` and `:`; case is folded to lowercase, duplicates are removed) go in the JSON `tags` array, a repeated `tags` form field, or, for a raw body, the `X-Note-Tags` header.
+ * The body is the note, a file, and `Content-Type` says which kind: `text/markdown` (UTF-8, at most 102400 bytes), or an image, `image/png`, `image/jpeg`, `image/gif` or `image/webp` (at most NOTEFEED_MAX_IMAGE_BYTES, default 5 MiB). Nothing is guessed: any other type, or none, is `415`, and so is a body that is not what the type says (an image is recognized by its first bytes; SVG is refused). It is stored byte for byte, with no resizing and no metadata stripped (EXIF such as GPS position stays in an image). Creates the feed with its first note, optionally protected by its own password (`X-Feed-Password`; 1 to 256 printable ASCII characters, with no space at the start or end) and with the read id in `X-Read-Id`; both are only used by the post that creates the feed. Posting to a protected feed needs its password. Also served at `POST /{feed}`, the short form curl one-liners use. The response names the note's `file` and where it is served, `file_url`, under the feed's read id (public like the read link). Metadata goes in headers: `X-Note-Title`, `X-Note-Tags` (at most 10 tags, each 1 to 32 characters of letters, digits, `-`, `_`, `.` and `:`; case is folded to lowercase, duplicates are removed), `X-Note-Alt` (images), `X-Note-Name` (the original file name).
  */
 export declare const postNote: <ThrowOnError extends boolean = false>(options: Options<PostNoteData, ThrowOnError>) => RequestResult<PostNoteResponses, PostNoteErrors, ThrowOnError>;
 /**
@@ -36,17 +36,17 @@ export declare const deleteNote: <ThrowOnError extends boolean = false>(options:
  */
 export declare const getNote: <ThrowOnError extends boolean = false>(options: Options<GetNoteData, ThrowOnError>) => RequestResult<GetNoteResponses, GetNoteErrors, ThrowOnError>;
 /**
- * Edit a note
+ * Change a note's title or alt text
  *
- * Replaces the note's markdown; its id and creation time stay, the title follows the new text. Needs the feed's password if it has one, and counts against the post rate limit. Read links can't edit. The body is as for posting: at most 102400 bytes, UTF-8, a `password` field is ignored.
+ * Sets the note's title and/or alt text (alt only for images). An empty string removes one: a markdown note's title follows its text again. At least one is needed. Needs the feed's password if it has one, and counts against the post rate limit. Read links can't change notes.
  */
-export declare const editNote: <ThrowOnError extends boolean = false>(options: Options<EditNoteData, ThrowOnError>) => RequestResult<EditNoteResponses, EditNoteErrors, ThrowOnError>;
+export declare const patchNote: <ThrowOnError extends boolean = false>(options: Options<PatchNoteData, ThrowOnError>) => RequestResult<PatchNoteResponses, PatchNoteErrors, ThrowOnError>;
 /**
- * Upload an image
+ * Replace a note's content
  *
- * The body is the image itself: PNG, JPEG, GIF or WebP, recognized by its first bytes, whatever `Content-Type` is sent (SVG is refused). Stored byte-for-byte, with no resizing and no metadata stripped (EXIF such as GPS position stays in the file), as the first 32 hex characters of its SHA-256 plus an extension: the same bytes always give the same URL. The URL is under the feed's read id, so it works in the feed page, the read-only view and RSS readers without any password. Needs the same credentials as posting and counts against the post rate limit. The feed must exist: it is created by its first note. The size limit is NOTEFEED_MAX_IMAGE_BYTES (default 5 MiB); images deleted only with the feed.
+ * The body is the new file, with the same rules as posting: a `Content-Type` that is one of the accepted types, a body that is what it declares. A note keeps its type, so the type must be the note's own (`415` otherwise). Id, creation time and metadata stay: the title of a markdown note without one set follows the new text. Change the title or alt text with `PATCH`. Needs the feed's password if it has one, and counts against the post rate limit. Read links can't edit.
  */
-export declare const uploadImage: <ThrowOnError extends boolean = false>(options: Options<UploadImageData, ThrowOnError>) => RequestResult<UploadImageResponses, UploadImageErrors, ThrowOnError>;
+export declare const editNote: <ThrowOnError extends boolean = false>(options: Options<EditNoteData, ThrowOnError>) => RequestResult<EditNoteResponses, EditNoteErrors, ThrowOnError>;
 /**
  * Delete a feed
  *
@@ -62,7 +62,7 @@ export declare const getFeed: <ThrowOnError extends boolean = false>(options: Op
 /**
  * Change a feed's settings
  *
- * Replaces both the title (at most 100 characters) and the description (at most 500); surrounding whitespace is trimmed and control characters are refused. `show_sender` (default true) shows who posted each note to readers; omitted leaves it as it is. `image` is the file name `uploadImage` returned for this feed (title image), empty to remove it, or omitted to leave it as it is; any other value is a 400. Needs the feed's password if it has one, and counts against the post rate limit. Only on a feed that exists: it is created by its first note. Read links can't change settings.
+ * Replaces both the title (at most 100 characters) and the description (at most 500); surrounding whitespace is trimmed and control characters are refused. `show_sender` (default true) shows who posted each note to readers; omitted leaves it as it is. `read_id` gives the feed another read link (3 to 64 characters: a-z, 0-9, - and _; empty for a random one): the old id is freed and answers like an unknown read id until another feed takes it, and the notes are not edited (a relative image link follows the new id, a full URL does not). A short readable read id is guessable, so protect the feed with a password if that matters. An instance can turn chosen read ids off (NOTEFEED_ALLOW_CUSTOM_IDS=0): then only an empty `read_id` is accepted. `image` is the file name `uploadImage` returned for this feed (title image), empty to remove it, or omitted to leave it as it is; any other value is a 400. Needs the feed's password if it has one, and counts against the post rate limit. Only on a feed that exists: it is created by its first note. Read links can't change settings.
  */
 export declare const updateFeed: <ThrowOnError extends boolean = false>(options: Options<UpdateFeedData, ThrowOnError>) => RequestResult<UpdateFeedResponses, UpdateFeedErrors, ThrowOnError>;
 /**

package/dist/generated/sdk.gen.js

@@ -13,14 +13,15 @@ export const listNotes = (options) => (options.client ?? client).get({
 /**
  * Post a note
  *
- * Creates the feed with its first note, optionally protected by its own password (`X-Feed-Password` header or a `password` field in the JSON or form body; 1 to 256 printable ASCII characters, with no space at the start or end). Posting to a protected feed needs that password. Also served at `POST /{feed}`, the short form the client packages and curl one-liners use. The body is at most 102400 bytes and must be UTF-8. `application/x-www-form-urlencoded` (what `curl -d` sends) is read as raw markdown, not as form fields. Tags (at most 10 tags, each 1 to 32 characters of letters, digits, `-`, `_`, `.` and `:`; case is folded to lowercase, duplicates are removed) go in the JSON `tags` array, a repeated `tags` form field, or, for a raw body, the `X-Note-Tags` header.
+ * The body is the note, a file, and `Content-Type` says which kind: `text/markdown` (UTF-8, at most 102400 bytes), or an image, `image/png`, `image/jpeg`, `image/gif` or `image/webp` (at most NOTEFEED_MAX_IMAGE_BYTES, default 5 MiB). Nothing is guessed: any other type, or none, is `415`, and so is a body that is not what the type says (an image is recognized by its first bytes; SVG is refused). It is stored byte for byte, with no resizing and no metadata stripped (EXIF such as GPS position stays in an image). Creates the feed with its first note, optionally protected by its own password (`X-Feed-Password`; 1 to 256 printable ASCII characters, with no space at the start or end) and with the read id in `X-Read-Id`; both are only used by the post that creates the feed. Posting to a protected feed needs its password. Also served at `POST /{feed}`, the short form curl one-liners use. The response names the note's `file` and where it is served, `file_url`, under the feed's read id (public like the read link). Metadata goes in headers: `X-Note-Title`, `X-Note-Tags` (at most 10 tags, each 1 to 32 characters of letters, digits, `-`, `_`, `.` and `:`; case is folded to lowercase, duplicates are removed), `X-Note-Alt` (images), `X-Note-Name` (the original file name).
  */
 export const postNote = (options) => (options.client ?? client).post({
+    bodySerializer: null,
     security: [{ scheme: 'bearer', type: 'http' }],
     url: '/api/v1/feeds/{feed}/notes',
     ...options,
     headers: {
-        'Content-Type': 'application/json',
+        'Content-Type': 'text/markdown',
         ...options.headers
     }
 });
@@ -43,11 +44,11 @@ export const getNote = (options) => (options.client ?? client).get({
     ...options
 });
 /**
- * Edit a note
+ * Change a note's title or alt text
  *
- * Replaces the note's markdown; its id and creation time stay, the title follows the new text. Needs the feed's password if it has one, and counts against the post rate limit. Read links can't edit. The body is as for posting: at most 102400 bytes, UTF-8, a `password` field is ignored.
+ * Sets the note's title and/or alt text (alt only for images). An empty string removes one: a markdown note's title follows its text again. At least one is needed. Needs the feed's password if it has one, and counts against the post rate limit. Read links can't change notes.
  */
-export const editNote = (options) => (options.client ?? client).put({
+export const patchNote = (options) => (options.client ?? client).patch({
     security: [{ scheme: 'bearer', type: 'http' }],
     url: '/api/v1/feeds/{feed}/notes/{id}',
     ...options,
@@ -57,17 +58,17 @@ export const editNote = (options) => (options.client ?? client).put({
     }
 });
 /**
- * Upload an image
+ * Replace a note's content
  *
- * The body is the image itself: PNG, JPEG, GIF or WebP, recognized by its first bytes, whatever `Content-Type` is sent (SVG is refused). Stored byte-for-byte, with no resizing and no metadata stripped (EXIF such as GPS position stays in the file), as the first 32 hex characters of its SHA-256 plus an extension: the same bytes always give the same URL. The URL is under the feed's read id, so it works in the feed page, the read-only view and RSS readers without any password. Needs the same credentials as posting and counts against the post rate limit. The feed must exist: it is created by its first note. The size limit is NOTEFEED_MAX_IMAGE_BYTES (default 5 MiB); images deleted only with the feed.
+ * The body is the new file, with the same rules as posting: a `Content-Type` that is one of the accepted types, a body that is what it declares. A note keeps its type, so the type must be the note's own (`415` otherwise). Id, creation time and metadata stay: the title of a markdown note without one set follows the new text. Change the title or alt text with `PATCH`. Needs the feed's password if it has one, and counts against the post rate limit. Read links can't edit.
  */
-export const uploadImage = (options) => (options.client ?? client).post({
+export const editNote = (options) => (options.client ?? client).put({
     bodySerializer: null,
     security: [{ scheme: 'bearer', type: 'http' }],
-    url: '/api/v1/feeds/{feed}/images',
+    url: '/api/v1/feeds/{feed}/notes/{id}',
     ...options,
     headers: {
-        'Content-Type': 'image/png',
+        'Content-Type': 'text/markdown',
         ...options.headers
     }
 });
@@ -94,7 +95,7 @@ export const getFeed = (options) => (options.client ?? client).get({
 /**
  * Change a feed's settings
  *
- * Replaces both the title (at most 100 characters) and the description (at most 500); surrounding whitespace is trimmed and control characters are refused. `show_sender` (default true) shows who posted each note to readers; omitted leaves it as it is. `image` is the file name `uploadImage` returned for this feed (title image), empty to remove it, or omitted to leave it as it is; any other value is a 400. Needs the feed's password if it has one, and counts against the post rate limit. Only on a feed that exists: it is created by its first note. Read links can't change settings.
+ * Replaces both the title (at most 100 characters) and the description (at most 500); surrounding whitespace is trimmed and control characters are refused. `show_sender` (default true) shows who posted each note to readers; omitted leaves it as it is. `read_id` gives the feed another read link (3 to 64 characters: a-z, 0-9, - and _; empty for a random one): the old id is freed and answers like an unknown read id until another feed takes it, and the notes are not edited (a relative image link follows the new id, a full URL does not). A short readable read id is guessable, so protect the feed with a password if that matters. An instance can turn chosen read ids off (NOTEFEED_ALLOW_CUSTOM_IDS=0): then only an empty `read_id` is accepted. `image` is the file name `uploadImage` returned for this feed (title image), empty to remove it, or omitted to leave it as it is; any other value is a 400. Needs the feed's password if it has one, and counts against the post rate limit. Only on a feed that exists: it is created by its first note. Read links can't change settings.
  */
 export const updateFeed = (options) => (options.client ?? client).put({
     security: [{ scheme: 'bearer', type: 'http' }],

package/dist/generated/types.gen.d.ts

@@ -3,17 +3,41 @@ export type ClientOptions = {
 };
 export type Note = {
     /**
-     * UTC time to the second plus a slug of the title
+     * The note's id: a UTC time to the second plus a random UUID for notes made here; any name without a dot for a file placed by hand
      */
     id: string;
     /**
-     * The first heading, or the first non-empty line; may be empty
+     * The media type of the note's file: `text/markdown`, `image/png`, `image/jpeg`, `image/gif` or `image/webp`
+     */
+    type: string;
+    /**
+     * The note's file name, `<id>.<extension>`
+     */
+    file: string;
+    /**
+     * Where the note's file is served, absolute, under the feed's read id (public like the read link); null while the feed has no read link
+     */
+    file_url: string | null;
+    /**
+     * The size of the note's file in bytes
+     */
+    size: number;
+    /**
+     * The title set for the note, else the first heading or the first non-empty line of a markdown note, else the picture's alt text; may be empty
      */
     title: string;
     /**
-     * The note, byte-for-byte as posted
+     * The note's text, byte-for-byte as posted: for a text type (markdown) only; absent for a picture
      */
-    markdown: string;
+    content?: string;
+    /**
+     * Alternative text of an image note, when it has one
+     */
+    alt?: string;
+    /**
+     * The file name an image was posted with, when it came with one
+     */
+    name?: string;
     /**
      * When the note was posted (UTC)
      */
@@ -55,20 +79,14 @@ export type Created = {
      * The feed's read-only RSS link, safe to share; null only if the server can't read the feed's stored read id, or if that id and the derived one both belong to other feeds
      */
     read_url: string | null;
-};
-export type ImageUploaded = {
     /**
-     * The stored file's name: 32 hex characters of the SHA-256 plus the extension. Pass it as a feed's `image` setting
+     * The note's file name, `<id>.<extension>`. For an image note, pass it as a feed's `image` setting
      */
     file: string;
     /**
-     * Where the image is served, absolute, under the feed's read id; public like the read link
-     */
-    url: string;
-    /**
-     * `![](url)`, to paste into a note
+     * Where the note's file is served, absolute, under the feed's read id (public like the read link); null while the feed has no read link
      */
-    markdown: string;
+    file_url: string | null;
 };
 export type Error = {
     /**
@@ -78,29 +96,17 @@ export type Error = {
     /**
      * Stable machine-readable code; absent only on a 500
      */
-    code?: 'invalid_feed' | 'reserved_feed' | 'auth' | 'rate_limited' | 'too_many_attempts' | 'feed_limit' | 'note_limit' | 'image_limit' | 'empty_note' | 'too_large' | 'unsupported_type' | 'invalid_body' | 'invalid_request' | 'not_found' | 'feed_exists';
+    code?: 'invalid_feed' | 'reserved_feed' | 'auth' | 'rate_limited' | 'too_many_attempts' | 'feed_limit' | 'note_limit' | 'image_limit' | 'empty_note' | 'too_large' | 'unsupported_type' | 'invalid_body' | 'invalid_request' | 'not_found' | 'feed_exists' | 'taken';
 };
-export type PostJson = {
-    markdown: string;
+export type NoteMeta = {
     /**
-     * Protects the feed: 1 to 256 printable ASCII characters, with no space at the start or end. Only honored on the post that creates the feed; an existing open feed answers 409. Empty is the same as leaving it out.
+     * The note's title, at most 100 characters, one line; empty or left out means the title is taken from the text (a markdown note) or there is none (an image)
      */
-    password?: string;
+    title?: string;
     /**
-     * Labels for the note: at most 10 tags, each 1 to 32 characters of letters, digits, `-`, `_`, `.` and `:`; case is folded to lowercase, duplicates are removed. Free labels, not verified, shown with the note (also to readers of the read link and RSS). Ignored when editing a note: an edit keeps its tags.
+     * Alternative text of an image note, at most 500 characters, one line
      */
-    tags?: Array<string>;
-};
-export type PostForm = {
-    markdown: string;
-    /**
-     * Protects the feed: 1 to 256 printable ASCII characters, with no space at the start or end. Only honored on the post that creates the feed; an existing open feed answers 409. Empty is the same as leaving it out.
-     */
-    password?: string;
-    /**
-     * Labels for the note: at most 10 tags, each 1 to 32 characters of letters, digits, `-`, `_`, `.` and `:`; case is folded to lowercase, duplicates are removed. Free labels, not verified, shown with the note (also to readers of the read link and RSS). Ignored when editing a note: an edit keeps its tags.
-     */
-    tags?: Array<string>;
+    alt?: string;
 };
 export type PasswordJson = {
     /**
@@ -125,6 +131,10 @@ export type FeedSettings = {
      * Whether readers (RSS, the read API and pages) see who posted each note; omitted leaves it as it is, a new feed starts with true
      */
     show_sender?: boolean;
+    /**
+     * A new read id (3 to 64 characters: a-z, 0-9, - and _), empty for a random one; omitted leaves it as it is. The old read link stops showing this feed, and may later show another one. Notes are not edited: a relative image link (`![](file)`) follows the new id, a full URL keeps the old one and is yours to change. Reserved feeds keep theirs. 409 when it is taken
+     */
+    read_id?: string;
 };
 export type Feed = {
     /**
@@ -223,16 +233,35 @@ export type ListNotesResponses = {
 };
 export type ListNotesResponse = ListNotesResponses[keyof ListNotesResponses];
 export type PostNoteData = {
-    body: PostJson;
+    /**
+     * The note, a file: its bytes, of the type `Content-Type` declares
+     */
+    body: Blob | File;
     headers?: {
         /**
          * The feed's own password, when it has one: to post, list or get, and (as the current password) to change or remove it. On the `POST` that creates a feed it sets the feed's password; on a `POST` to an existing feed that has none it answers 409. An empty value is the same as no header, so a `POST` with an empty one creates an open feed.
          */
         'X-Feed-Password'?: string;
+        /**
+         * The read id the feed gets when this post creates it: 3 to 64 characters (a-z, 0-9, - and _), random when left out or empty, ignored for a feed that exists. A short readable one is guessable: protect the feed with a password if that matters. 409 when it is taken
+         */
+        'X-Read-Id'?: string;
+        /**
+         * The note's title, for a raw body; a JSON or form body's own `title` wins. At most 100 characters, one line.
+         */
+        'X-Note-Title'?: string;
         /**
          * Tags for the note, comma-separated (`ci,deploy`): at most 10 tags, each 1 to 32 characters of letters, digits, `-`, `_`, `.` and `:`; case is folded to lowercase, duplicates are removed. For a raw markdown body; a JSON or form body's own `tags` wins. Empty is none.
          */
         'X-Note-Tags'?: string;
+        /**
+         * For an image body: its alternative text; a form's own `alt` wins.
+         */
+        'X-Note-Alt'?: string;
+        /**
+         * For an image body: the picture's original file name, kept with the note (at most 200 characters)
+         */
+        'X-Note-Name'?: string;
     };
     path: {
         /**
@@ -245,7 +274,7 @@ export type PostNoteData = {
 };
 export type PostNoteErrors = {
     /**
-     * Invalid or reserved feed name; empty note; bad JSON, form or UTF-8; a new password that is not printable ASCII; invalid tags
+     * Invalid or reserved feed name; a blank note; a bad title, alt text or tags; a new password that is not printable ASCII
      */
     400: Error;
     /**
@@ -253,15 +282,15 @@ export type PostNoteErrors = {
      */
     401: Error;
     /**
-     * A password was sent for a feed that already exists without one: it can't be claimed
+     * A password was sent for a feed that already exists without one: it can't be claimed; or the chosen read id is taken
      */
     409: Error;
     /**
-     * Body over 102400 bytes
+     * Markdown over 102400 bytes, or an image over NOTEFEED_MAX_IMAGE_BYTES
      */
     413: Error;
     /**
-     * Unsupported content type
+     * Content-Type missing or not one of the accepted types, or the body is not what it declares
      */
     415: Error;
     /**
@@ -269,7 +298,7 @@ export type PostNoteErrors = {
      */
     429: Error;
     /**
-     * NOTEFEED_MAX_FEEDS or NOTEFEED_MAX_NOTES_PER_FEED reached
+     * NOTEFEED_MAX_FEEDS, NOTEFEED_MAX_NOTES_PER_FEED or NOTEFEED_MAX_IMAGES_PER_FEED reached
      */
     507: Error;
 };
@@ -375,8 +404,8 @@ export type GetNoteResponses = {
     200: Note;
 };
 export type GetNoteResponse = GetNoteResponses[keyof GetNoteResponses];
-export type EditNoteData = {
-    body: PostJson;
+export type PatchNoteData = {
+    body: NoteMeta;
     headers?: {
         /**
          * The feed's own password, when it has one: to post, list or get, and (as the current password) to change or remove it. On the `POST` that creates a feed it sets the feed's password; on a `POST` to an existing feed that has none it answers 409. An empty value is the same as no header, so a `POST` with an empty one creates an open feed.
@@ -396,9 +425,9 @@ export type EditNoteData = {
     query?: never;
     url: '/api/v1/feeds/{feed}/notes/{id}';
 };
-export type EditNoteErrors = {
+export type PatchNoteErrors = {
     /**
-     * Invalid or reserved feed name; empty note; bad JSON, form or UTF-8
+     * Invalid or reserved feed name; nothing to change; a bad title or alt text; alt for a note that has none; bad JSON
      */
     400: Error;
     /**
@@ -410,11 +439,7 @@ export type EditNoteErrors = {
      */
     404: Error;
     /**
-     * Body over 102400 bytes
-     */
-    413: Error;
-    /**
-     * Unsupported content type
+     * Content-Type is not application/json
      */
     415: Error;
     /**
@@ -422,17 +447,17 @@ export type EditNoteErrors = {
      */
     429: Error;
 };
-export type EditNoteError = EditNoteErrors[keyof EditNoteErrors];
-export type EditNoteResponses = {
+export type PatchNoteError = PatchNoteErrors[keyof PatchNoteErrors];
+export type PatchNoteResponses = {
     /**
      * The note as it is now
      */
     200: Note;
 };
-export type EditNoteResponse = EditNoteResponses[keyof EditNoteResponses];
-export type UploadImageData = {
+export type PatchNoteResponse = PatchNoteResponses[keyof PatchNoteResponses];
+export type EditNoteData = {
     /**
-     * The image's bytes: PNG, JPEG, GIF or WebP, recognized by their first bytes, not by the Content-Type
+     * The note, a file: its bytes, of the type `Content-Type` declares
      */
     body: Blob | File;
     headers?: {
@@ -446,13 +471,17 @@ export type UploadImageData = {
          * The feed's name. It is the write key: anyone who knows it can post.
          */
         feed: string;
+        /**
+         * The note's id
+         */
+        id: string;
     };
     query?: never;
-    url: '/api/v1/feeds/{feed}/images';
+    url: '/api/v1/feeds/{feed}/notes/{id}';
 };
-export type UploadImageErrors = {
+export type EditNoteErrors = {
     /**
-     * Invalid or reserved feed name
+     * Invalid or reserved feed name; a blank note
      */
     400: Error;
     /**
@@ -460,34 +489,30 @@ export type UploadImageErrors = {
      */
     401: Error;
     /**
-     * No such feed
+     * No such note
      */
     404: Error;
     /**
-     * Body over NOTEFEED_MAX_IMAGE_BYTES
+     * Markdown over 102400 bytes, or an image over NOTEFEED_MAX_IMAGE_BYTES
      */
     413: Error;
     /**
-     * Not a PNG, JPEG, GIF or WebP image
+     * Content-Type missing, not accepted or not the note's own type, or the body is not what it declares
      */
     415: Error;
     /**
-     * Too many posts, uploads, edits and deletes, or wrong passwords, from this client
+     * Too many posts, edits and deletes, or wrong passwords, from this client
      */
     429: Error;
-    /**
-     * NOTEFEED_MAX_IMAGES_PER_FEED reached
-     */
-    507: Error;
 };
-export type UploadImageError = UploadImageErrors[keyof UploadImageErrors];
-export type UploadImageResponses = {
+export type EditNoteError = EditNoteErrors[keyof EditNoteErrors];
+export type EditNoteResponses = {
     /**
-     * Stored (or already there)
+     * The note as it is now
      */
-    201: ImageUploaded;
+    200: Note;
 };
-export type UploadImageResponse = UploadImageResponses[keyof UploadImageResponses];
+export type EditNoteResponse = EditNoteResponses[keyof EditNoteResponses];
 export type DeleteFeedData = {
     body?: never;
     headers?: {
@@ -593,7 +618,7 @@ export type UpdateFeedData = {
 };
 export type UpdateFeedErrors = {
     /**
-     * Invalid or reserved feed name, bad JSON, or a title or description that is too long or has control characters
+     * Invalid or reserved feed name, bad JSON, a title or description that is too long or has control characters, a malformed read id, a reserved feed's read id, or chosen read ids turned off
      */
     400: Error;
     /**
@@ -604,6 +629,10 @@ export type UpdateFeedErrors = {
      * No such feed
      */
     404: Error;
+    /**
+     * The read id belongs to another feed or is held back for a reserved one
+     */
+    409: Error;
     /**
      * Too many posts, edits and deletes, or wrong passwords, from this client
      */
@@ -707,7 +736,7 @@ export type GetReadFeedData = {
     body?: never;
     path: {
         /**
-         * The feed's read id, from its read link: 22 random characters, or the feed's own name for a reserved feed. Read-only; never reveals the name of any other feed.
+         * The feed's read id, from its read link: 22 random characters, one the feed's owner chose, or the feed's own name for a reserved feed. Read-only; never reveals the name of any other feed.
          */
         readId: string;
     };
@@ -732,7 +761,7 @@ export type ListReadNotesData = {
     body?: never;
     path: {
         /**
-         * The feed's read id, from its read link: 22 random characters, or the feed's own name for a reserved feed. Read-only; never reveals the name of any other feed.
+         * The feed's read id, from its read link: 22 random characters, one the feed's owner chose, or the feed's own name for a reserved feed. Read-only; never reveals the name of any other feed.
          */
         readId: string;
     };
@@ -774,7 +803,7 @@ export type GetReadNoteData = {
     body?: never;
     path: {
         /**
-         * The feed's read id, from its read link: 22 random characters, or the feed's own name for a reserved feed. Read-only; never reveals the name of any other feed.
+         * The feed's read id, from its read link: 22 random characters, one the feed's owner chose, or the feed's own name for a reserved feed. Read-only; never reveals the name of any other feed.
          */
         readId: string;
         /**

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { AuthError, Client, ConfigError, InvalidRequestError, LimitReachedError, NotefeedError, NotFoundError, NoteTooLargeError, RateLimitedError, } from "./client.js";
-export type { ClientOptions, Created, ErrorCode, Feed, FeedSettings, ImageUploaded, Note } from "./client.js";
+export type { Attachment, ClientOptions, Created, ErrorCode, Feed, FeedSettings, Note } from "./client.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notefeed",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Client and CLI for notefeed, a self-hosted inbox for markdown notes that you read back as RSS.",
   "license": "Apache-2.0",
   "author": "Marcel Bruckner",