notefeed 0.7.0 → 0.9.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 with the text in one request, and the server swaps `![](chart.png)` for each file name (`null` content posts only the pictures) (`notefeed post "…" --attach chart.png` does the same); nothing is posted when one is refused. 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/
+Full documentation: https://docs.notefeed.me/integrations/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,30 @@ 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 attachments = await Promise.all((values.attach ?? []).map(attachment));
+            // Pictures alone need no text; the result is then the first picture, whose URL is also in `attachments`.
+            const noText = attachments.length > 0 && text === undefined && !values.file;
+            const input = noText ? { content: null, type: undefined, name: undefined } : await read(text, values.file, values.type, io);
+            // The server refuses a file name next to attachments: the text has none then.
+            const note = await client(values).post(input.content, { type: input.type, title: values.title, tags: values.tag, name: attachments.length ? undefined : input.name, attachments });
+            io.stdout.write(`${[...(noText ? [] : [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 +83,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;
@@ -108,26 +116,42 @@ 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 with the note: its name is the file's (the client checks it), 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`);
+    try {
+        return { name: basename(path), 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;
@@ -49,19 +56,49 @@ 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` are pictures posted with the note in one request: `![](name)` in the markdown shows one (a picture the text never refers to is
+     * added at the end), and `Created.attachments` lists them in order. `tags` label the pictures too. `content` may be `null` when there are
+     * attachments: only the pictures are posted, `title` and `tags` go on each, and the result is the first picture plus `attachments`. Checked
+     * here, before anything is sent (ConfigError): a name given twice, an attachment that is not a picture, content that is not markdown, `alt` or
+     * `name` with attachments. What a name may be is the server's rule (docs/using/pictures.md, "Posting a note with its pictures"): a name it refuses is an
+     * InvalidRequestError, `attachment "<name>": ...`, and whenever the server refuses any part (its message names it) nothing is posted.
+     */
+    post(content: string | Uint8Array | Blob | null, 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 +112,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;
@@ -54,9 +54,23 @@ const BY_CODE = {
     invalid_body: InvalidRequestError,
     invalid_request: InvalidRequestError,
     feed_exists: InvalidRequestError,
+    taken: InvalidRequestError,
     unsupported_type: InvalidRequestError,
 };
+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 };
+}
 export class Client {
     url;
     feed;
@@ -87,23 +101,83 @@ 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` are pictures posted with the note in one request: `![](name)` in the markdown shows one (a picture the text never refers to is
+     * added at the end), and `Created.attachments` lists them in order. `tags` label the pictures too. `content` may be `null` when there are
+     * attachments: only the pictures are posted, `title` and `tags` go on each, and the result is the first picture plus `attachments`. Checked
+     * here, before anything is sent (ConfigError): a name given twice, an attachment that is not a picture, content that is not markdown, `alt` or
+     * `name` with attachments. What a name may be is the server's rule (docs/using/pictures.md, "Posting a note with its pictures"): a name it refuses is an
+     * InvalidRequestError, `attachment "<name>": ...`, and whenever the server refuses any part (its message names it) nothing is posted.
+     */
+    async post(content, options = {}) {
+        const { attachments = [], ...own } = options;
+        if (content === null && attachments.length === 0)
+            throw new ConfigError("no content and no attachments");
+        if (attachments.length === 0)
+            return { ...(await this.postOne(content, own)), attachments: [] };
+        if (content !== null && (typeof content !== "string" || (own.type ?? "text/markdown") !== "text/markdown"))
+            throw new ConfigError("attachments go with a markdown string");
+        if (own.alt || own.name)
+            throw new ConfigError("alt and name do not go with attachments: give each attachment its alt");
+        const form = new FormData();
+        if (content !== null)
+            form.append("text", new Blob([content], { type: "text/markdown" }));
+        for (const a of attachments) {
+            if (attachments.findIndex((b) => b.name === a.name) !== attachments.indexOf(a))
+                throw new ConfigError(`attachment "${a.name}" is given twice`);
+            const { body, type } = asFile(a.content, a.type);
+            if (!IMAGE_TYPES.includes(type))
+                throw new ConfigError(`attachment "${a.name}" must be a picture (${IMAGE_TYPES.join(", ")})`);
+            form.append("file", new Blob([body], { type }), a.name);
+            if (a.alt)
+                form.append(`alt.${a.name}`, a.alt);
+        }
+        const feed = this.feedFor(own.feed);
+        const headers = {
+            ...this.opts(own.feedPassword).headers,
+            "Content-Type": null, // fetch sets multipart/form-data with its boundary
+            ...(own.title && { "X-Note-Title": headerValue(own.title) }),
+            ...(own.tags?.length && { "X-Note-Tags": own.tags.join(",") }),
+            ...(own.readId && { "X-Read-Id": own.readId }),
+        };
+        const created = await this.call(postNote({ client: this.api, path: { feed }, body: form, headers, signal: AbortSignal.timeout(this.timeoutMs) }));
+        return { ...created, attachments: created.attachments ?? [] };
+    }
+    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 +189,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, MultipartNote, Note, NoteEdited, NoteList, NoteMeta, PasswordJson, PatchNoteData, PatchNoteError, PatchNoteErrors, PatchNoteResponse, PatchNoteResponses, Posted, 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). A markdown note with its pictures is one `multipart/form-data` request: a `text` part (the markdown, a field or a file part; a file part keeps its line breaks, a field's are sent as CRLF), `file` parts (up to 10 pictures, each with its file name and image `Content-Type`) and `alt.<file name>` fields. The pictures are stored first, each as its own note named by its file name, then the text with its references to them (`![](chart.png)`, `[x]: chart.png`, as written or percent-decoded) swapped for the stored files; a picture it never refers to is appended as `![](file)`. Everything is checked before the first write, and a failed write removes what the request stored: all or nothing. `X-Note-Alt` and `X-Note-Name` are 400. The answer has `attachments`, the stored pictures in the order of the `file` parts. The `text` part is optional: `X-Note-Title` goes on the text note and `X-Note-Tags` on every note; with no `text` part only the pictures are stored, each with the title, and the answer's top level is the first picture. A refused multipart post that would have created a protected feed creates nothing.
  */
 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. A markdown note with its pictures is one `multipart/form-data` request: a `text` part (the markdown, a field or a file part; a file part keeps its line breaks, a field's are sent as CRLF), `file` parts (up to 10 pictures, each with its file name and image `Content-Type`) and `alt.<file name>` fields. The pictures are stored first, each as its own note named by its file name, then the text with its references to them (`![](chart.png)`, `[x]: chart.png`, as written or percent-decoded) swapped for the stored files; a picture it never refers to is appended as `![](file)`. Everything is checked before the first write, and a failed write removes what the request stored: all or nothing. `X-Note-Alt` and `X-Note-Name` are 400. The answer has `attachments`, the stored pictures in the order of the `file` parts. On a `PUT` the `text` part is required and the note must be a markdown note; the note keeps its own title and tags, `X-Note-Tags` goes on the new pictures. A raw body ignores `X-Note-Tags`. The note is looked up first: a missing note is `404` and an image note `415` whatever the body holds.
  */
-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 and text-direction override 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). A markdown note with its pictures is one `multipart/form-data` request: a `text` part (the markdown, a field or a file part; a file part keeps its line breaks, a field's are sent as CRLF), `file` parts (up to 10 pictures, each with its file name and image `Content-Type`) and `alt.<file name>` fields. The pictures are stored first, each as its own note named by its file name, then the text with its references to them (`![](chart.png)`, `[x]: chart.png`, as written or percent-decoded) swapped for the stored files; a picture it never refers to is appended as `![](file)`. Everything is checked before the first write, and a failed write removes what the request stored: all or nothing. `X-Note-Alt` and `X-Note-Name` are 400. The answer has `attachments`, the stored pictures in the order of the `file` parts. The `text` part is optional: `X-Note-Title` goes on the text note and `X-Note-Tags` on every note; with no `text` part only the pictures are stored, each with the title, and the answer's top level is the first picture. A refused multipart post that would have created a protected feed creates nothing.
  */
 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. A markdown note with its pictures is one `multipart/form-data` request: a `text` part (the markdown, a field or a file part; a file part keeps its line breaks, a field's are sent as CRLF), `file` parts (up to 10 pictures, each with its file name and image `Content-Type`) and `alt.<file name>` fields. The pictures are stored first, each as its own note named by its file name, then the text with its references to them (`![](chart.png)`, `[x]: chart.png`, as written or percent-decoded) swapped for the stored files; a picture it never refers to is appended as `![](file)`. Everything is checked before the first write, and a failed write removes what the request stored: all or nothing. `X-Note-Alt` and `X-Note-Name` are 400. The answer has `attachments`, the stored pictures in the order of the `file` parts. On a `PUT` the `text` part is required and the note must be a markdown note; the note keeps its own title and tags, `X-Note-Tags` goes on the new pictures. A raw body ignores `X-Note-Tags`. The note is looked up first: a missing note is `404` and an image note `415` whatever the body holds.
  */
-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 and text-direction override 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
+     */
+    content?: string;
+    /**
+     * Alternative text of an image note, when it has one
      */
-    markdown: string;
+    alt?: string;
+    /**
+     * The file name an image was posted with, when it came with one
+     */
+    name?: string;
     /**
      * When the note was posted (UTC)
      */
@@ -55,52 +79,132 @@ 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;
+    /**
+     * The note's file name, `<id>.<extension>`. For an image note, pass it as a feed's `image` setting
+     */
+    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 note the post is about: its text note, or with no `text` part its first picture
+ */
+export type Posted = {
+    id: string;
+    /**
+     * The note's page in the web UI
+     */
+    url: string;
+    /**
+     * The feed's page in the web UI
+     */
+    feed_url: string;
+    /**
+     * 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;
+    /**
+     * The note's file name, `<id>.<extension>`. For an image note, pass it as a feed's `image` setting
+     */
+    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;
+    /**
+     * A multipart request's pictures, one per `file` part, in their order; absent for a raw body
+     */
+    attachments?: Array<Created>;
 };
-export type ImageUploaded = {
+export type NoteEdited = {
+    /**
+     * 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 stored file's name: 32 hex characters of the SHA-256 plus the extension. Pass it as a feed's `image` setting
+     * 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 image is served, absolute, under the feed's read id; public like the read link
+     * 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's text, byte-for-byte as posted: for a text type (markdown) only; absent for a picture
+     */
+    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)
+     */
+    created_at: string;
+    /**
+     * The note's page in the web UI
      */
     url: string;
     /**
-     * `![](url)`, to paste into a note
+     * Verified sign-in name of the poster; absent when the note was posted without a sign-in
+     */
+    sender?: string | null;
+    /**
+     * Labels the poster gave the note (not verified, and shown to readers like the note itself); empty when none
      */
-    markdown: string;
+    tags: Array<string>;
+    /**
+     * A multipart request's pictures, one per `file` part, in their order; absent for a raw body
+     */
+    attachments?: Array<Created>;
 };
-export type Error = {
+export type MultipartNote = {
     /**
-     * A short reason, for people
+     * The markdown note (UTF-8): a field, or a file part (its name is ignored; its type, if any, `text/markdown` or `application/octet-stream`) to keep its line breaks as they are, since a form field's are sent as CRLF. At most one; required on a PUT. Its references to the files (`![](chart.png)`, `[x]: chart.png`) are swapped for the stored files; a file it never refers to is appended as `![](file)`
      */
-    error: string;
+    text?: string;
     /**
-     * Stable machine-readable code; absent only on a 500
+     * A picture: up to 10 parts, each with a file name (one path segment, 1 to 200 characters, unique in the request) and its image `Content-Type`. An `alt.<file name>` field gives one its alternative text
      */
-    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';
+    file?: Array<Blob | File>;
 };
-export type PostJson = {
-    markdown: string;
+export type Error = {
     /**
-     * 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.
+     * A short reason, for people
      */
-    password?: string;
+    error: 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.
+     * Stable machine-readable code; absent only on a 500
      */
-    tags?: Array<string>;
+    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 PostForm = {
-    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 (control and text-direction override characters are refused); 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 (control and text-direction override characters are refused)
      */
-    tags?: Array<string>;
+    alt?: string;
 };
 export type PasswordJson = {
     /**
@@ -110,11 +214,11 @@ export type PasswordJson = {
 };
 export type FeedSettings = {
     /**
-     * Display title, at most 100 characters, one line; empty means none (the feed's name is shown)
+     * Display title, at most 100 characters, one line (control and text-direction override characters are refused); empty means none (the feed's name is shown)
      */
     title: string;
     /**
-     * Description, at most 500 characters, one line; may be empty
+     * Description, at most 500 characters, one line (control and text-direction override characters are refused); may be empty
      */
     description: string;
     /**
@@ -125,6 +229,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 = {
     /**
@@ -132,11 +240,11 @@ export type Feed = {
      */
     name: string;
     /**
-     * Display title, at most 100 characters, one line; empty means none (the feed's name is shown)
+     * Display title, at most 100 characters, one line (control and text-direction override characters are refused); empty means none (the feed's name is shown)
      */
     title: string;
     /**
-     * Description, at most 500 characters, one line; may be empty
+     * Description, at most 500 characters, one line (control and text-direction override characters are refused); may be empty
      */
     description: string;
     /**
@@ -158,11 +266,11 @@ export type Feed = {
 };
 export type ReadFeed = {
     /**
-     * Display title, at most 100 characters, one line; empty means none (the feed's name is shown)
+     * Display title, at most 100 characters, one line (control and text-direction override characters are refused); empty means none (the feed's name is shown)
      */
     title: string;
     /**
-     * Description, at most 500 characters, one line; may be empty
+     * Description, at most 500 characters, one line (control and text-direction override characters are refused); may be empty
      */
     description: string;
     /**
@@ -223,16 +331,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, with no control or text-direction override characters.
+         */
+        '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 +372,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; a multipart body with an unexpected part, no `text` and no `file`, more than 10 files, a bad or repeated file name, a text sent with pictures that takes too long to read (`NOTEFEED_PARSE_TIMEOUT_MS`), or `X-Note-Alt` / `X-Note-Name`
      */
     400: Error;
     /**
@@ -253,15 +380,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 (each picture of a multipart body too), or a multipart body over 102400 bytes plus 10 images plus 64 KiB
      */
     413: Error;
     /**
-     * Unsupported content type
+     * Content-Type missing or not one of the accepted types, or the body (or a multipart body's picture) is not what it declares
      */
     415: Error;
     /**
@@ -269,16 +396,16 @@ 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;
 };
 export type PostNoteError = PostNoteErrors[keyof PostNoteErrors];
 export type PostNoteResponses = {
     /**
-     * Stored
+     * Stored: the note, and with a multipart body its pictures
      */
-    201: Created;
+    201: Posted;
 };
 export type PostNoteResponse = PostNoteResponses[keyof PostNoteResponses];
 export type DeleteNoteData = {
@@ -375,8 +502,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 +523,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 +537,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 +545,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?: {
@@ -440,19 +563,27 @@ export type UploadImageData = {
          * 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;
+        /**
+         * Only for a multipart body: the tags go on the new pictures (the note keeps its own). A raw body ignores it. Comma-separated, empty is none.
+         */
+        'X-Note-Tags'?: string;
     };
     path: {
         /**
          * 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; a multipart body with an unexpected part, no `text`, more than 10 files, a bad or repeated file name, a text sent with pictures that takes too long to read (`NOTEFEED_PARSE_TIMEOUT_MS`), or `X-Note-Alt` / `X-Note-Name`
      */
     400: Error;
     /**
@@ -460,19 +591,19 @@ 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 (each picture of a multipart body too), or a multipart body over 102400 bytes plus 10 images plus 64 KiB
      */
     413: Error;
     /**
-     * Not a PNG, JPEG, GIF or WebP image
+     * Content-Type missing, not accepted or not the note's own type (a multipart body is for a markdown note), or the body (or a picture) 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;
     /**
@@ -480,14 +611,14 @@ export type UploadImageErrors = {
      */
     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, and with a multipart body the new pictures
      */
-    201: ImageUploaded;
+    200: NoteEdited;
 };
-export type UploadImageResponse = UploadImageResponses[keyof UploadImageResponses];
+export type EditNoteResponse = EditNoteResponses[keyof EditNoteResponses];
 export type DeleteFeedData = {
     body?: never;
     headers?: {
@@ -593,7 +724,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 or text-direction override characters, a malformed read id, a reserved feed's read id, or chosen read ids turned off
      */
     400: Error;
     /**
@@ -604,6 +735,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 +842,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 +867,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 +909,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.9.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",
@@ -39,7 +39,7 @@
     "url": "git+https://github.com/Marceltov/notefeed.git",
     "directory": "packages/js"
   },
-  "homepage": "https://docs.notefeed.me/clients/",
+  "homepage": "https://docs.notefeed.me/integrations/clients/",
   "bugs": {
     "url": "https://github.com/Marceltov/notefeed/issues"
   },