notefeed 0.26.0 → 0.28.0

package/README.md

@@ -8,8 +8,8 @@ export NOTEFEED_URL=https://notes.example.com NOTEFEED_FEED=homelab-7f3k2q9x4m8w
 npx notefeed post "# Backup finished"
 backup.sh 2>&1 | npx notefeed post -
 npx notefeed notes --limit 5
-npx notefeed edit 20260929T140512Z-backup-finished "# Backup finished, verified"
-npx notefeed delete 20260929T140512Z-backup-finished
+npx notefeed edit Vq3xH8mTn2KfLw0aZr9bYe "# Backup finished, verified"
+npx notefeed delete Vq3xH8mTn2KfLw0aZr9bYe
 ```
 
 ```js
@@ -18,11 +18,13 @@ import { Client } from "notefeed";
 const client = new Client({ url: "https://notes.example.com", feed: "homelab-7f3k2q9x4m8wz" }); // password: "..." if the instance has one
 const created = await client.post("# Deploy done\nversion 1.4.2");
 console.log(created.url, created.read_url);
-for await (const note of client.notes()) console.log(note.created_at, note.title); // newest first, page by page
+for await (const note of client.notes()) console.log(note.date, note.title); // newest first, page by page
 ```
 
 `read_url` is `null` for a feed without a read link (rare; see the operations docs).
 
+Every note has a date, now unless you give one: `client.post(text, { date: "2025-03-01T09:30:00Z" })` (a `Date`, an ISO 8601 date-time with its offset, or a date alone for midnight UTC; any time from 1970 to 9999), or `notefeed post "…" --date 2025-03-01`. The note takes its place in the feed by that date. A date in the future schedules the note: readers see it from then on. `await client.update(id, { date })` (`notefeed update <id> --date …`) moves a note.
+
 `Client.fromEnv()` reads `NOTEFEED_URL` / `NOTEFEED_FEED` / `NOTEFEED_PASSWORD`; so does the `notefeed` command, unless given `--url` / `--feed` / `--password`.
 
 A feed can have its own password, which gates reading, listing and posting to it. Pass `feedPassword: "..."` to `new Client(...)` (or per call, e.g. `client.post(text, { feedPassword })`), or set `NOTEFEED_FEED_PASSWORD`, which `fromEnv()` and the `notefeed` command both read (there is deliberately no flag, so it stays out of shell history). It is sent as `X-Feed-Password`; `Authorization` stays the instance password. A feed password is 1 to 256 printable ASCII characters with no space at the start or end; an empty one is the same as none.
@@ -31,6 +33,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, a picture that is too large is a `NoteTooLargeError`, and an instance that takes no pictures (`NOTEFEED_IMAGE_UPLOADS=0`) answers every picture with an `ImagesOffError`. 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.
+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, a picture that is too large is a `NoteTooLargeError`, and an instance that takes no pictures (`NOTEFEED_IMAGE_UPLOADS=0`) answers every picture with an `ImagesOffError`. The server checks the bytes against the declared type. `await client.update(id, { title, alt, date })` changes a note's title, a picture's alt text or a note's date, 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/integrations/clients/

package/dist/cli.js

@@ -7,9 +7,9 @@ import { Client, ConfigError, NotefeedError } from "./client.js";
 class UsageError extends Error {
 }
 const USAGE = [
-    "usage: notefeed post <text | - | --file PATH> [--type MEDIA_TYPE] [--title TITLE] [--tag TAG]... [--attach PATH]... [--url URL] [--feed FEED] [--password PASSWORD]",
+    "usage: notefeed post <text | - | --file PATH> [--type MEDIA_TYPE] [--title TITLE] [--tag TAG]... [--attach PATH]... [--date WHEN] [--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 update <id> [--title TITLE] [--alt ALT] [--date WHEN] [--url URL] [--feed FEED] [--password PASSWORD]",
     "       notefeed delete <id> [--url URL] [--feed FEED] [--password PASSWORD]",
     "       notefeed notes [--limit N] [--tag TAG] [--json] [--url URL] [--feed FEED] [--password PASSWORD]",
 ].join("\n");
@@ -30,6 +30,7 @@ export async function main(argv, io = process) {
                 title: { type: "string" },
                 alt: { type: "string" },
                 tag: { type: "string", multiple: true },
+                date: { type: "string" },
                 attach: { type: "string", multiple: true },
                 limit: { type: "string" },
                 json: { type: "boolean" },
@@ -53,7 +54,7 @@ export async function main(argv, io = process) {
             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 });
+            const note = await client(values).post(input.content, { type: input.type, title: values.title, tags: values.tag, date: values.date, name: attachments.length ? undefined : input.name, attachments });
             io.stdout.write(`${[...(noText ? [] : [note.url]), ...note.attachments.map((a) => a.url)].join("\n")}\n`);
             return 0;
         }
@@ -64,9 +65,9 @@ export async function main(argv, io = process) {
             return 0;
         }
         if (command === "update" && text !== undefined && !rest.length) {
-            if (values.title === undefined && values.alt === undefined)
-                throw new UsageError("give --title and/or --alt");
-            const note = await client(values).update(text, { title: values.title, alt: values.alt });
+            if (values.title === undefined && values.alt === undefined && values.date === undefined)
+                throw new UsageError("give --title, --alt and/or --date");
+            const note = await client(values).update(text, { title: values.title, alt: values.alt, date: values.date });
             io.stdout.write(`${note.url}\n`);
             return 0;
         }
@@ -81,9 +82,9 @@ export async function main(argv, io = process) {
             let left = limit;
             for await (const n of client(values).notes({ pageSize: Math.min(limit, 100), tag: values.tag?.[0] })) {
                 // To the second, UTC: the same form as the Python CLI, so scripts read either the same way.
-                const when = new Date(n.created_at).toISOString().replace(/\.\d+Z$/, "Z");
+                const when = new Date(n.date).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, 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 };
+                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, date: 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;

package/dist/client.d.ts

@@ -67,14 +67,15 @@ export declare class 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). `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
+     * text. `alt` is a picture's alternative text, `name` the file's original name. `date` is the note's date, if not now: a
+     * Date or an ISO 8601 date-time with its offset (`2026-10-01T09:30:00Z`) or a date alone (midnight UTC), from 1970 to 9999; a future date schedules the note: readers see it from then on. `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).
      * `licenseKey` goes with `feedPassword` on the post that creates the feed, on an instance that sells licenses: a feed password is for
      * licensed feeds, and the new feed gets the license (a `license_required` error without the key; ignored on an existing feed).
      *
      * `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
+     * attachments: only the pictures are posted, `title`, `tags` and `date` 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.
@@ -87,6 +88,7 @@ export declare class Client {
         tags?: string[];
         alt?: string;
         name?: string;
+        date?: string | Date;
         readId?: string;
         licenseKey?: string;
         attachments?: Attachment[];
@@ -100,10 +102,11 @@ export declare class Client {
         feedPassword?: string;
         type?: string;
     }): Promise<Note>;
-    /** Set a note's title and/or alt text (alt for pictures); `""` removes one, so a markdown note's title follows its text again. Same options as post(). */
+    /** Set a note's title, alt text (for pictures) and/or date (as in post(); a future one schedules the note); `""` removes a title or alt, so a markdown note's title follows its text again. Same options as post(). */
     update(id: string, meta: {
         title?: string;
         alt?: string;
+        date?: string | Date;
     }, options?: {
         feed?: string;
         feedPassword?: string;

package/dist/client.js

@@ -68,6 +68,8 @@ const FEED_RE = /^[a-z0-9_-]{1,64}$/; // same rule as the server; reserved names
 // 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("");
+// X-Note-Date: a Date as its UTC time, a string as given (the server checks it).
+const dateString = (at) => (typeof at === "string" ? at : at.toISOString());
 // 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")
@@ -115,14 +117,15 @@ export class 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). `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
+     * text. `alt` is a picture's alternative text, `name` the file's original name. `date` is the note's date, if not now: a
+     * Date or an ISO 8601 date-time with its offset (`2026-10-01T09:30:00Z`) or a date alone (midnight UTC), from 1970 to 9999; a future date schedules the note: readers see it from then on. `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).
      * `licenseKey` goes with `feedPassword` on the post that creates the feed, on an instance that sells licenses: a feed password is for
      * licensed feeds, and the new feed gets the license (a `license_required` error without the key; ignored on an existing feed).
      *
      * `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
+     * attachments: only the pictures are posted, `title`, `tags` and `date` 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.
@@ -156,6 +159,7 @@ export class Client {
             "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.date && { "X-Note-Date": dateString(own.date) }),
             ...(own.readId && { "X-Read-Id": own.readId }),
             ...(own.licenseKey && { "X-License-Key": own.licenseKey }),
         };
@@ -172,6 +176,7 @@ export class Client {
             ...(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.date && { "X-Note-Date": dateString(options.date) }),
             ...(options.readId && { "X-Read-Id": options.readId }),
             ...(options.licenseKey && { "X-License-Key": options.licenseKey }),
         };
@@ -184,10 +189,12 @@ export class Client {
         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) }));
     }
-    /** 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(). */
+    /** Set a note's title, alt text (for pictures) and/or date (as in post(); a future one schedules the note); `""` removes a title or alt, 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(patchNote({ client: this.api, path: { feed, id }, body: meta, ...this.opts(options.feedPassword) }));
+        const { date, ...rest } = meta;
+        const body = { ...rest, ...(date !== undefined && { date: dateString(date) }) };
+        return this.call(patchNote({ client: this.api, path: { feed, id }, body, ...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 = {}) {

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. Where licenses are sold, a feed password needs one: the post that creates the feed protected brings the license key in `X-License-Key`, or is refused with `402`. 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.
+ * 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. Where licenses are sold, a feed password needs one: the post that creates the feed protected brings the license key in `X-License-Key`, or is refused with `402`. 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), `X-Note-Date` (where it is placed in the feed: a past date backdates it, a future one schedules it). 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, `X-Note-Tags` on every note, `X-Note-Date` on the text note (its pictures take the milliseconds just before it); 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,9 +36,9 @@ 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>;
 /**
- * Change a note's title or alt text
+ * Change a note's title, alt text or date
  *
- * 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.
+ * Sets the note's title, alt text (only for images) and/or date. An empty title or alt removes it: a markdown note's title follows its text again. A new date moves the note in the feed, with its attachments; a date after now schedules it. Id and links stay. 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 patchNote: <ThrowOnError extends boolean = false>(options: Options<PatchNoteData, ThrowOnError>) => RequestResult<PatchNoteResponses, PatchNoteErrors, 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. Where licenses are sold, a feed password needs one: the post that creates the feed protected brings the license key in `X-License-Key`, or is refused with `402`. 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.
+ * 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. Where licenses are sold, a feed password needs one: the post that creates the feed protected brings the license key in `X-License-Key`, or is refused with `402`. 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), `X-Note-Date` (where it is placed in the feed: a past date backdates it, a future one schedules it). 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, `X-Note-Tags` on every note, `X-Note-Date` on the text note (its pictures take the milliseconds just before it); 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,
@@ -44,9 +44,9 @@ export const getNote = (options) => (options.client ?? client).get({
     ...options
 });
 /**
- * Change a note's title or alt text
+ * Change a note's title, alt text or date
  *
- * 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.
+ * Sets the note's title, alt text (only for images) and/or date. An empty title or alt removes it: a markdown note's title follows its text again. A new date moves the note in the feed, with its attachments; a date after now schedules it. Id and links stay. 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 patchNote = (options) => (options.client ?? client).patch({
     security: [{ scheme: 'bearer', type: 'http' }],

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

@@ -3,7 +3,7 @@ export type ClientOptions = {
 };
 export type Note = {
     /**
-     * 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
+     * The note's id: 22 random characters (base64url) for notes made here, older notes may have another form; any name without a dot for a file placed by hand. It says nothing about the note's date
      */
     id: string;
     /**
@@ -39,9 +39,13 @@ export type Note = {
      */
     name?: string;
     /**
-     * When the note was posted (UTC)
+     * Where the note is placed in the feed (UTC): when it was posted, unless a date was given or changed; lists are ordered by it
      */
-    created_at: string;
+    date: string;
+    /**
+     * Present, and true, when the note's date is after now: it is stored, and readers see it from its date on. Absent for every other note
+     */
+    scheduled?: true;
     /**
      * The note's page in the web UI
      */
@@ -124,7 +128,7 @@ export type Posted = {
 };
 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
+     * The note's id: 22 random characters (base64url) for notes made here, older notes may have another form; any name without a dot for a file placed by hand. It says nothing about the note's date
      */
     id: string;
     /**
@@ -160,9 +164,13 @@ export type NoteEdited = {
      */
     name?: string;
     /**
-     * When the note was posted (UTC)
+     * Where the note is placed in the feed (UTC): when it was posted, unless a date was given or changed; lists are ordered by it
+     */
+    date: string;
+    /**
+     * Present, and true, when the note's date is after now: it is stored, and readers see it from its date on. Absent for every other note
      */
-    created_at: string;
+    scheduled?: true;
     /**
      * The note's page in the web UI
      */
@@ -213,6 +221,10 @@ export type NoteMeta = {
      * Alternative text of an image note, at most 500 characters, one line (control and text-direction override characters are refused)
      */
     alt?: string;
+    /**
+     * An ISO 8601 date and time with its offset (`2026-10-01T09:30:00Z`, `2026-10-01T11:30:00+02:00`) or a date alone (midnight UTC). When the note is placed in the feed, from 1970 to 9999. A time after now schedules it: readers see it from then on. The note's attachments move with it.
+     */
+    date?: string;
 };
 export type PasswordJson = {
     /**
@@ -390,6 +402,10 @@ export type PostNoteData = {
          * For an image body: the picture's original file name, kept with the note (at most 200 characters)
          */
         'X-Note-Name'?: string;
+        /**
+         * An ISO 8601 date and time with its offset (`2026-10-01T09:30:00Z`, `2026-10-01T11:30:00+02:00`) or a date alone (midnight UTC). When the note is placed in the feed, from 1970 to 9999. A time after now schedules it: readers see it from then on. Empty is now.
+         */
+        'X-Note-Date'?: string;
     };
     path: {
         /**
@@ -402,7 +418,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; a license key that is none; 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`
+     * Invalid or reserved feed name; a blank note; a bad title, alt text, tags or `X-Note-Date`; `X-Note-Created` (the header's name before 0.28.0); a new password that is not printable ASCII; a license key that is none; 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;
     /**
@@ -583,7 +599,7 @@ export type PatchNoteData = {
 };
 export type PatchNoteErrors = {
     /**
-     * Invalid or reserved feed name; nothing to change; a bad title or alt text; alt for a note that has none; bad JSON
+     * Invalid or reserved feed name; nothing to change; a bad title, alt text or date; alt for a note that has none; bad JSON
      */
     400: Error;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notefeed",
-  "version": "0.26.0",
+  "version": "0.28.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",