notefeed 0.8.0 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # notefeed
 
-Post and read markdown notes on a [notefeed](https://github.com/Marceltov/notefeed) server from Node or the command line. No dependencies; Node 20 or newer.
+Post and read markdown notes on a [notefeed](https://github.com/notefeed/notefeed) server from Node or the command line. No dependencies; Node 20 or newer.
 
 ```sh
 npm install notefeed
@@ -31,6 +31,6 @@ A posted note can be changed or removed: `await client.edit(id, content)` replac
 
 A feed can have a title and a description, and can be deleted: `await client.feedInfo()` returns `{ name, title, description, protected, read_url }`, `await client.updateFeed({ title, description })` replaces both (an empty string clears one) and returns the feed, and `await client.deleteFeed()` removes the feed with all its notes for good. All three take the same `{ feed, feedPassword }` options as `post`, and a feed that doesn't exist is a `NotFoundError`. Anyone who can post to a feed can do this, and deleting is permanent; there are no `notefeed` commands for it.
 
-A picture is a note of its own: `await client.post(bytes, { type: "image/png", alt: "…" })` takes a `Uint8Array` or a `Blob` (PNG, JPEG, GIF or WebP; a Blob's own type is used if you leave `type` out) and returns what a markdown post returns, with the picture's `file` and `file_url` added. Write `![](file)` in a markdown note to show it; the feed is created by its first note, and a picture that is too large is a `NoteTooLargeError`. The server checks the bytes against the declared type. `await client.update(id, { title, alt })` changes a note's title or a picture's alt text, and `await client.edit(id, content)` replaces its content. `await client.updateFeed({ title, description, image: file })` makes a picture the feed's title image (`image: ""` removes it; leaving `image` out keeps it). `notefeed post --file photo.png` posts a file (the type comes from the extension, or `--type`). To post a note with its pictures in one call, `await client.post(text, { attachments: [{ name: "chart.png", content: bytes, type: "image/png" }] })` posts them first and swaps `![](chart.png)` for each file name (`notefeed post "…" --attach chart.png` does the same); a failure carries the pictures already posted as `posted`. Pictures are public to anyone with the feed's read link, and metadata such as EXIF is not removed.
+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

@@ -48,10 +48,13 @@ export async function main(argv, io = process) {
         }
         const [command, text, ...rest] = positionals;
         if (command === "post" && !rest.length) {
-            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`);
+            // 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) {
@@ -91,9 +94,6 @@ 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)
@@ -141,16 +141,13 @@ async function read(text, file, type, io) {
         throw new UsageError('give the note text, "-" for stdin, or --file PATH');
     return { content: text, type: type ?? "text/markdown" };
 }
-// A picture to post first: its name is the file's, its type comes from the extension.
+// 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`);
-    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 };
+        return { name: basename(path), content: await readFile(path), type };
     }
     catch (e) {
         throw new UsageError(`cannot read ${path}: ${e.code ?? e.message}`);

package/dist/client.d.ts

@@ -22,9 +22,6 @@ 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 {
@@ -70,12 +67,14 @@ export declare class Client {
      * 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.
+     * `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, options?: {
+    post(content: string | Uint8Array | Blob | null, options?: {
         feed?: string;
         feedPassword?: string;
         type?: string;

package/dist/client.js

@@ -14,9 +14,6 @@ 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 {
@@ -60,7 +57,6 @@ const BY_CODE = {
     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
@@ -75,18 +71,6 @@ function asFile(content, type) {
         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;
@@ -128,55 +112,46 @@ export class Client {
      * 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.
+     * `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 (typeof content !== "string")
-            throw new ConfigError("attachments go with a markdown string");
-        if ((own.type ?? "text/markdown") !== "text/markdown")
+        if (content !== null && (typeof content !== "string" || (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 (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(", ")})`);
-            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;
+            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);

package/dist/generated/index.d.ts

@@ -1,2 +1,2 @@
 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';
+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/sdk.gen.d.ts

@@ -22,7 +22,7 @@ export declare const listNotes: <ThrowOnError extends boolean = false>(options:
 /**
  * Post a note
  *
- * 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).
+ * 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>;
 /**
@@ -44,7 +44,7 @@ export declare const patchNote: <ThrowOnError extends boolean = false>(options:
 /**
  * Replace a note's content
  *
- * 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.
+ * 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 editNote: <ThrowOnError extends boolean = false>(options: Options<EditNoteData, ThrowOnError>) => RequestResult<EditNoteResponses, EditNoteErrors, ThrowOnError>;
 /**
@@ -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. `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.
+ * 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,7 +13,7 @@ export const listNotes = (options) => (options.client ?? client).get({
 /**
  * Post a note
  *
- * 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).
+ * 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,
@@ -60,7 +60,7 @@ export const patchNote = (options) => (options.client ?? client).patch({
 /**
  * Replace a note's content
  *
- * 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.
+ * 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 editNote = (options) => (options.client ?? client).put({
     bodySerializer: null,
@@ -95,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. `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.
+ * 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

@@ -88,6 +88,104 @@ export type Created = {
      */
     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 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 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'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;
+    /**
+     * 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
+     */
+    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 MultipartNote = {
+    /**
+     * 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)`
+     */
+    text?: string;
+    /**
+     * 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
+     */
+    file?: Array<Blob | File>;
+};
 export type Error = {
     /**
      * A short reason, for people
@@ -100,11 +198,11 @@ export type Error = {
 };
 export type NoteMeta = {
     /**
-     * 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)
+     * 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)
      */
     title?: string;
     /**
-     * Alternative text of an image note, at most 500 characters, one line
+     * Alternative text of an image note, at most 500 characters, one line (control and text-direction override characters are refused)
      */
     alt?: string;
 };
@@ -116,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;
     /**
@@ -142,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;
     /**
@@ -168,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;
     /**
@@ -247,7 +345,7 @@ export type PostNoteData = {
          */
         '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.
+         * 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;
         /**
@@ -274,7 +372,7 @@ export type PostNoteData = {
 };
 export type PostNoteErrors = {
     /**
-     * Invalid or reserved feed name; a blank note; a bad title, alt text or tags; a new password that is not printable ASCII
+     * 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;
     /**
@@ -286,11 +384,11 @@ export type PostNoteErrors = {
      */
     409: Error;
     /**
-     * Markdown over 102400 bytes, or an image 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;
     /**
-     * Content-Type missing or not one of the accepted types, or the body is not what it declares
+     * 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;
     /**
@@ -305,9 +403,9 @@ export type PostNoteErrors = {
 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 = {
@@ -465,6 +563,10 @@ export type EditNoteData = {
          * 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: {
         /**
@@ -481,7 +583,7 @@ export type EditNoteData = {
 };
 export type EditNoteErrors = {
     /**
-     * Invalid or reserved feed name; a blank note
+     * 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;
     /**
@@ -493,24 +595,28 @@ export type EditNoteErrors = {
      */
     404: Error;
     /**
-     * Markdown over 102400 bytes, or an image 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;
     /**
-     * Content-Type missing, not accepted or not the note's own type, or the body is not what it declares
+     * 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, edits and deletes, or wrong passwords, from this client
      */
     429: Error;
+    /**
+     * NOTEFEED_MAX_IMAGES_PER_FEED reached
+     */
+    507: Error;
 };
 export type EditNoteError = EditNoteErrors[keyof EditNoteErrors];
 export type EditNoteResponses = {
     /**
-     * The note as it is now
+     * The note as it is now, and with a multipart body the new pictures
      */
-    200: Note;
+    200: NoteEdited;
 };
 export type EditNoteResponse = EditNoteResponses[keyof EditNoteResponses];
 export type DeleteFeedData = {
@@ -618,7 +724,7 @@ export type UpdateFeedData = {
 };
 export type UpdateFeedErrors = {
     /**
-     * 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
+     * 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;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notefeed",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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",
@@ -36,12 +36,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Marceltov/notefeed.git",
+    "url": "git+https://github.com/notefeed/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"
+    "url": "https://github.com/notefeed/notefeed/issues"
   },
   "devDependencies": {
     "@types/node": "^20",