@solarpunkltd/swarm-chat-js 7.1.0 → 7.3.0

package/dist/message/index.d.ts

@@ -1,2 +1,3 @@
 export * from './message.js';
 export * from './entry.js';
+export * from './note.js';

package/dist/message/note.d.ts

@@ -0,0 +1,38 @@
+import { Identifier, Reference } from '@ethersphere/bee-js';
+import { z } from 'zod';
+/**
+ * Slot notes: the chat server's announcement, after a stretch of wall-clock time in which messages landed, of the
+ * newest feed slot it has written. A reader asks for a note only once its time slot is over, and asks for a feed slot
+ * only once a note has named it, so it never asks Bee for an address that is not written yet. Bee answers a chunk it
+ * could not find by skipping every peer it asked for that address for a minute, which is what made new messages
+ * arrive about forty seconds late while readers polled the next slot.
+ *
+ * Time slot `s` covers `[s * slotMs, (s + 1) * slotMs)` in Unix milliseconds. Its note is a single owner chunk signed
+ * by the chat feed's key, at the identifier keccak256(`<topic>/note/<slotMs>/<s>`).
+ */
+export declare const NOTE_VERSION = 1;
+export declare const DEFAULT_NOTE_SLOT_MS = 2000;
+export declare const DEFAULT_NOTE_HEARTBEAT_MS = 30000;
+/** A note is far below one chunk, so it is a single owner chunk with its payload inline. */
+export declare const MAX_NOTE_BYTES = 256;
+export declare const slotNoteSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    newest: z.ZodNumber;
+    writtenAt: z.ZodNumber;
+}, z.core.$strict>;
+export type SlotNote = z.infer<typeof slotNoteSchema>;
+/** The time slot that holds the instant `timeMs`. */
+export declare function noteSlotOf(timeMs: number, slotMs: number): number;
+/** The instant time slot `slot` ends, which is the first instant of the next one. */
+export declare function noteSlotEnd(slot: number, slotMs: number): number;
+export declare function noteIdentifierText(topic: string, slotMs: number, slot: number): string;
+export declare function noteIdentifier(topic: string, slotMs: number, slot: number): Identifier;
+/**
+ * Where a note lives, the address `GET /chunks/<address>` reads it from: keccak256 of the identifier and the owner,
+ * the single owner chunk rule.
+ */
+export declare function noteAddress(topic: string, slotMs: number, slot: number, owner: string): Reference;
+/** The payload, with its fields in this order, so two encodings of one note are the same bytes. */
+export declare function encodeSlotNote(note: Omit<SlotNote, 'v'>): Uint8Array;
+/** A note, or null for anything that fails the strict check, which a reader treats as no note at all. */
+export declare function parseSlotNote(payload: Uint8Array): SlotNote | null;

package/dist/message.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@ethersphere/bee-js"),t=require("zod");var n=7,r=2048,i=128,a=500,o=20,s={TEXT:`text`,THREAD:`thread`,REACTION:`reaction`};function c(e){let t=0;for(let n of e)t++;return t}function l(e){return t.z.string().regex(RegExp(`^[0-9a-f]{${e}}$`),`expected ${e} lowercase hex characters`)}function u(e,n){return t.z.string().refine(t=>{let r=c(t);return r>=e&&r<=n},`expected ${e} to ${n} characters`)}var d=l(32),f=t.z.strictObject({v:t.z.literal(7),topic:u(1,128),id:d,type:t.z.enum([s.TEXT,s.THREAD,s.REACTION]),target:t.z.union([t.z.literal(``),d]),text:u(1,500),name:u(1,20),addr:l(40),ts:t.z.number().int().nonnegative().max(2**53-1),sig:l(130)}).refine(e=>e.type===s.TEXT==(e.target===``),{message:`a text message has no target, a thread reply or a reaction names one`,path:[`target`]}),p=class extends Error{constructor(e,t){super(`chat message refused (${e}): ${t}`),this.reason=e,this.name=`ChatMessageError`}},m=new TextEncoder,h=new TextDecoder(`utf-8`,{fatal:!0});function g(e){return m.encode(JSON.stringify([e.v,e.topic,e.id,e.type,e.target,e.text,e.name,e.addr,e.ts]))}function _(e){let t={v:e.v,topic:e.topic,id:e.id,type:e.type,target:e.target,text:e.text,name:e.name,addr:e.addr,ts:e.ts,sig:e.sig};return m.encode(JSON.stringify(t))}function v(){let e=crypto.getRandomValues(new Uint8Array(16));return Array.from(e,e=>e.toString(16).padStart(2,`0`)).join(``)}function y(e){return e.issues.map(e=>`${e.path.join(`.`)||`message`}: ${e.message}`).join(`, `)}function b(t,n){let i=t instanceof e.PrivateKey?t:new e.PrivateKey(t),a={v:7,topic:n.topic,id:n.id??v(),type:n.type,target:n.target??``,text:n.text,name:n.name,addr:i.publicKey().address().toHex(),ts:n.ts??Date.now()},o={...a,sig:`0`.repeat(130)},s=f.safeParse(o);if(!s.success)throw new p(`shape`,y(s.error));let c=_(o).byteLength;if(c>2048)throw new p(`too-large`,`${c} bytes, the cap is ${r}`);let l={...a,sig:i.sign(g(a)).toHex()};return{message:l,bytes:_(l)}}function x(t){try{return new e.Signature(t.sig).recoverPublicKey(g(t)).address().toHex()===t.addr}catch{return!1}}function S(e){let t=f.safeParse(e);return t.success?x(t.data)?{ok:!0,message:t.data}:{ok:!1,reason:`signature`,detail:`the signature was not made by addr over these fields`}:{ok:!1,reason:`shape`,detail:y(t.error)}}function C(e){if(e.byteLength>2048)return{ok:!1,reason:`too-large`,detail:`${e.byteLength} bytes, the cap is ${r}`};let t;try{t=h.decode(e)}catch{return{ok:!1,reason:`not-utf8`,detail:`the payload is not valid UTF-8`}}let n;try{n=JSON.parse(t)}catch{return{ok:!1,reason:`not-json`,detail:`the payload is not JSON`}}return S(n)}var w=4096,T=t.z.string().regex(/^[0-9a-f]{64}([0-9a-f]{64})?$/,`expected a 64 or 128 hex character reference`),E=t.z.number().int().nonnegative().max(2**53-1),D=t.z.strictObject({ref:T,toSeq:E}),O=t.z.strictObject({v:t.z.literal(7),seq:E,at:E,msg:f,history:D.nullable()}),k=t.z.strictObject({seq:E,at:E,msg:f}),A=t.z.strictObject({v:t.z.literal(7),topic:t.z.string().min(1),fromSeq:E,toSeq:E,messages:t.z.array(t.z.unknown()),prev:D.nullable()}).refine(e=>e.fromSeq<=e.toSeq,{message:`fromSeq is after toSeq`,path:[`fromSeq`]}),j=new TextDecoder(`utf-8`,{fatal:!0});function M(e){let t;try{t=j.decode(e)}catch{return{ok:!1,reason:`not-utf8`,detail:`the payload is not valid UTF-8`}}try{return{ok:!0,value:JSON.parse(t)}}catch{return{ok:!1,reason:`not-json`,detail:`the payload is not JSON`}}}function N(e){return e.issues.map(e=>`${e.path.join(`.`)||`value`}: ${e.message}`).join(`, `)}function P(e,t,n){let r=M(e);if(!r.ok)return r;let i=O.safeParse(r.value);return i.success?i.data.seq===t?i.data.msg.topic===n?{ok:!0,value:i.data}:{ok:!1,reason:`mismatch`,detail:`the message belongs to another chat`}:{ok:!1,reason:`mismatch`,detail:`seq ${i.data.seq} at index ${t}`}:{ok:!1,reason:`shape`,detail:N(i.error)}}function F(e,t,n){let r=M(e);if(!r.ok)return r;let i=A.safeParse(r.value);if(!i.success)return{ok:!1,reason:`shape`,detail:N(i.error)};if(i.data.topic!==t||i.data.toSeq!==n.toSeq)return{ok:!1,reason:`mismatch`,detail:`the file is not the one its link names`};let{fromSeq:a,toSeq:o,prev:s}=i.data,c=[],l=0;for(let e of i.data.messages){let n=k.safeParse(e);n.success&&n.data.seq>=a&&n.data.seq<=o&&n.data.msg.topic===t?c.push(n.data):l++}return{ok:!0,value:{topic:t,fromSeq:a,toSeq:o,rows:c,prev:s,skipped:l}}}exports.ChatMessageError=p,exports.MAX_ENTRY_BYTES=w,exports.MAX_MESSAGE_BYTES=r,exports.MAX_NAME_CHARACTERS=o,exports.MAX_TEXT_CHARACTERS=a,exports.MAX_TOPIC_CHARACTERS=i,exports.MESSAGE_VERSION=n,exports.MessageType=s,exports.chatMessageSchema=f,exports.checkChatMessage=S,exports.countCharacters=c,exports.createChatMessage=b,exports.encodeChatMessage=_,exports.feedEntrySchema=O,exports.hasValidSignature=x,exports.historyFileSchema=A,exports.historyLinkSchema=D,exports.historyRowSchema=k,exports.newMessageId=v,exports.parseChatMessage=C,exports.parseFeedEntry=P,exports.parseHistoryFile=F,exports.signedBytes=g;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@ethersphere/bee-js"),t=require("zod");var n=7,r=2048,i=128,a=500,o=20,s={TEXT:`text`,THREAD:`thread`,REACTION:`reaction`};function c(e){let t=0;for(let n of e)t++;return t}function l(e){return t.z.string().regex(RegExp(`^[0-9a-f]{${e}}$`),`expected ${e} lowercase hex characters`)}function u(e,n){return t.z.string().refine(t=>{let r=c(t);return r>=e&&r<=n},`expected ${e} to ${n} characters`)}var d=l(32),f=t.z.strictObject({v:t.z.literal(7),topic:u(1,128),id:d,type:t.z.enum([s.TEXT,s.THREAD,s.REACTION]),target:t.z.union([t.z.literal(``),d]),text:u(1,500),name:u(1,20),addr:l(40),ts:t.z.number().int().nonnegative().max(2**53-1),sig:l(130)}).refine(e=>e.type===s.TEXT==(e.target===``),{message:`a text message has no target, a thread reply or a reaction names one`,path:[`target`]}),p=class extends Error{constructor(e,t){super(`chat message refused (${e}): ${t}`),this.reason=e,this.name=`ChatMessageError`}},m=new TextEncoder,h=new TextDecoder(`utf-8`,{fatal:!0});function g(e){return m.encode(JSON.stringify([e.v,e.topic,e.id,e.type,e.target,e.text,e.name,e.addr,e.ts]))}function _(e){let t={v:e.v,topic:e.topic,id:e.id,type:e.type,target:e.target,text:e.text,name:e.name,addr:e.addr,ts:e.ts,sig:e.sig};return m.encode(JSON.stringify(t))}function v(){let e=crypto.getRandomValues(new Uint8Array(16));return Array.from(e,e=>e.toString(16).padStart(2,`0`)).join(``)}function y(e){return e.issues.map(e=>`${e.path.join(`.`)||`message`}: ${e.message}`).join(`, `)}function b(t,n){let i=t instanceof e.PrivateKey?t:new e.PrivateKey(t),a={v:7,topic:n.topic,id:n.id??v(),type:n.type,target:n.target??``,text:n.text,name:n.name,addr:i.publicKey().address().toHex(),ts:n.ts??Date.now()},o={...a,sig:`0`.repeat(130)},s=f.safeParse(o);if(!s.success)throw new p(`shape`,y(s.error));let c=_(o).byteLength;if(c>2048)throw new p(`too-large`,`${c} bytes, the cap is ${r}`);let l={...a,sig:i.sign(g(a)).toHex()};return{message:l,bytes:_(l)}}function x(t){try{return new e.Signature(t.sig).recoverPublicKey(g(t)).address().toHex()===t.addr}catch{return!1}}function S(e){let t=f.safeParse(e);return t.success?x(t.data)?{ok:!0,message:t.data}:{ok:!1,reason:`signature`,detail:`the signature was not made by addr over these fields`}:{ok:!1,reason:`shape`,detail:y(t.error)}}function C(e){if(e.byteLength>2048)return{ok:!1,reason:`too-large`,detail:`${e.byteLength} bytes, the cap is ${r}`};let t;try{t=h.decode(e)}catch{return{ok:!1,reason:`not-utf8`,detail:`the payload is not valid UTF-8`}}let n;try{n=JSON.parse(t)}catch{return{ok:!1,reason:`not-json`,detail:`the payload is not JSON`}}return S(n)}var w=4096,T=t.z.string().regex(/^[0-9a-f]{64}([0-9a-f]{64})?$/,`expected a 64 or 128 hex character reference`),E=t.z.number().int().nonnegative().max(2**53-1),D=t.z.strictObject({ref:T,toSeq:E}),O=t.z.strictObject({v:t.z.literal(7),seq:E,at:E,msg:f,history:D.nullable()}),k=t.z.strictObject({seq:E,at:E,msg:f}),A=t.z.strictObject({v:t.z.literal(7),topic:t.z.string().min(1),fromSeq:E,toSeq:E,messages:t.z.array(t.z.unknown()),prev:D.nullable()}).refine(e=>e.fromSeq<=e.toSeq,{message:`fromSeq is after toSeq`,path:[`fromSeq`]}),j=new TextDecoder(`utf-8`,{fatal:!0});function M(e){let t;try{t=j.decode(e)}catch{return{ok:!1,reason:`not-utf8`,detail:`the payload is not valid UTF-8`}}try{return{ok:!0,value:JSON.parse(t)}}catch{return{ok:!1,reason:`not-json`,detail:`the payload is not JSON`}}}function N(e){return e.issues.map(e=>`${e.path.join(`.`)||`value`}: ${e.message}`).join(`, `)}function P(e,t,n){let r=M(e);if(!r.ok)return r;let i=O.safeParse(r.value);return i.success?i.data.seq===t?i.data.msg.topic===n?{ok:!0,value:i.data}:{ok:!1,reason:`mismatch`,detail:`the message belongs to another chat`}:{ok:!1,reason:`mismatch`,detail:`seq ${i.data.seq} at index ${t}`}:{ok:!1,reason:`shape`,detail:N(i.error)}}function F(e,t,n){let r=M(e);if(!r.ok)return r;let i=A.safeParse(r.value);if(!i.success)return{ok:!1,reason:`shape`,detail:N(i.error)};if(i.data.topic!==t||i.data.toSeq!==n.toSeq)return{ok:!1,reason:`mismatch`,detail:`the file is not the one its link names`};let{fromSeq:a,toSeq:o,prev:s}=i.data,c=[],l=0;for(let e of i.data.messages){let n=k.safeParse(e);n.success&&n.data.seq>=a&&n.data.seq<=o&&n.data.msg.topic===t?c.push(n.data):l++}return{ok:!0,value:{topic:t,fromSeq:a,toSeq:o,rows:c,prev:s,skipped:l}}}var I=1,L=2e3,R=3e4,z=256,B=t.z.strictObject({v:t.z.literal(1),newest:t.z.number().int().min(-1).max(2**53-1),writtenAt:t.z.number().int().nonnegative().max(2**53-1)});function V(e){if(!Number.isInteger(e)||e<=0)throw RangeError(`a note slot is a positive whole number of milliseconds, not ${e}`)}function H(e,t){return V(t),Math.floor(e/t)}function U(e,t){return V(t),(e+1)*t}function W(e,t,n){return`${e}/note/${t}/${n}`}function G(t,n,r){return e.Identifier.fromString(W(t,n,r))}function K(t,n,r,i){let a=G(t,n,r);return new e.Reference(e.Bytes.keccak256(e.Bytes.concat(a.toUint8Array(),new e.EthAddress(i).toUint8Array())))}var q=new TextEncoder,J=new TextDecoder(`utf-8`,{fatal:!0});function Y(e){let t={v:1,newest:e.newest,writtenAt:e.writtenAt};return q.encode(JSON.stringify(t))}function X(e){if(e.length>256)return null;try{let t=B.safeParse(JSON.parse(J.decode(e)));return t.success?t.data:null}catch{return null}}exports.ChatMessageError=p,exports.DEFAULT_NOTE_HEARTBEAT_MS=R,exports.DEFAULT_NOTE_SLOT_MS=L,exports.MAX_ENTRY_BYTES=w,exports.MAX_MESSAGE_BYTES=r,exports.MAX_NAME_CHARACTERS=o,exports.MAX_NOTE_BYTES=z,exports.MAX_TEXT_CHARACTERS=a,exports.MAX_TOPIC_CHARACTERS=i,exports.MESSAGE_VERSION=n,exports.MessageType=s,exports.NOTE_VERSION=I,exports.chatMessageSchema=f,exports.checkChatMessage=S,exports.countCharacters=c,exports.createChatMessage=b,exports.encodeChatMessage=_,exports.encodeSlotNote=Y,exports.feedEntrySchema=O,exports.hasValidSignature=x,exports.historyFileSchema=A,exports.historyLinkSchema=D,exports.historyRowSchema=k,exports.newMessageId=v,exports.noteAddress=K,exports.noteIdentifier=G,exports.noteIdentifierText=W,exports.noteSlotEnd=U,exports.noteSlotOf=H,exports.parseChatMessage=C,exports.parseFeedEntry=P,exports.parseHistoryFile=F,exports.parseSlotNote=X,exports.signedBytes=g,exports.slotNoteSchema=B;

package/dist/message.js

@@ -1,50 +1,50 @@
-import { PrivateKey as e, Signature as t } from "@ethersphere/bee-js";
-import { z as n } from "zod";
+import { Bytes as e, EthAddress as t, Identifier as n, PrivateKey as r, Reference as i, Signature as a } from "@ethersphere/bee-js";
+import { z as o } from "zod";
 //#region src/message/message.ts
-var r = 7, i = 2048, a = 128, o = 500, s = 20, c = {
+var s = 7, c = 2048, l = 128, u = 500, d = 20, f = {
 	TEXT: "text",
 	THREAD: "thread",
 	REACTION: "reaction"
 };
-function l(e) {
+function p(e) {
 	let t = 0;
 	for (let n of e) t++;
 	return t;
 }
-function u(e) {
-	return n.string().regex(RegExp(`^[0-9a-f]{${e}}$`), `expected ${e} lowercase hex characters`);
+function m(e) {
+	return o.string().regex(RegExp(`^[0-9a-f]{${e}}$`), `expected ${e} lowercase hex characters`);
 }
-function d(e, t) {
-	return n.string().refine((n) => {
-		let r = l(n);
+function h(e, t) {
+	return o.string().refine((n) => {
+		let r = p(n);
 		return r >= e && r <= t;
 	}, `expected ${e} to ${t} characters`);
 }
-var f = u(32), p = n.strictObject({
-	v: n.literal(7),
-	topic: d(1, 128),
-	id: f,
-	type: n.enum([
-		c.TEXT,
-		c.THREAD,
-		c.REACTION
+var g = m(32), _ = o.strictObject({
+	v: o.literal(7),
+	topic: h(1, 128),
+	id: g,
+	type: o.enum([
+		f.TEXT,
+		f.THREAD,
+		f.REACTION
 	]),
-	target: n.union([n.literal(""), f]),
-	text: d(1, 500),
-	name: d(1, 20),
-	addr: u(40),
-	ts: n.number().int().nonnegative().max(2 ** 53 - 1),
-	sig: u(130)
-}).refine((e) => e.type === c.TEXT == (e.target === ""), {
+	target: o.union([o.literal(""), g]),
+	text: h(1, 500),
+	name: h(1, 20),
+	addr: m(40),
+	ts: o.number().int().nonnegative().max(2 ** 53 - 1),
+	sig: m(130)
+}).refine((e) => e.type === f.TEXT == (e.target === ""), {
 	message: "a text message has no target, a thread reply or a reaction names one",
 	path: ["target"]
-}), m = class extends Error {
+}), v = class extends Error {
 	constructor(e, t) {
 		super(`chat message refused (${e}): ${t}`), this.reason = e, this.name = "ChatMessageError";
 	}
-}, h = new TextEncoder(), g = new TextDecoder("utf-8", { fatal: !0 });
-function _(e) {
-	return h.encode(JSON.stringify([
+}, y = new TextEncoder(), b = new TextDecoder("utf-8", { fatal: !0 });
+function x(e) {
+	return y.encode(JSON.stringify([
 		e.v,
 		e.topic,
 		e.id,
@@ -56,7 +56,7 @@ function _(e) {
 		e.ts
 	]));
 }
-function v(e) {
+function S(e) {
 	let t = {
 		v: e.v,
 		topic: e.topic,
@@ -69,52 +69,52 @@ function v(e) {
 		ts: e.ts,
 		sig: e.sig
 	};
-	return h.encode(JSON.stringify(t));
+	return y.encode(JSON.stringify(t));
 }
-function y() {
+function C() {
 	let e = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16));
 	return Array.from(e, (e) => e.toString(16).padStart(2, "0")).join("");
 }
-function b(e) {
+function w(e) {
 	return e.issues.map((e) => `${e.path.join(".") || "message"}: ${e.message}`).join(", ");
 }
-function x(t, n) {
-	let r = t instanceof e ? t : new e(t), a = {
+function T(e, t) {
+	let n = e instanceof r ? e : new r(e), i = {
 		v: 7,
-		topic: n.topic,
-		id: n.id ?? y(),
-		type: n.type,
-		target: n.target ?? "",
-		text: n.text,
-		name: n.name,
-		addr: r.publicKey().address().toHex(),
-		ts: n.ts ?? Date.now()
-	}, o = {
-		...a,
+		topic: t.topic,
+		id: t.id ?? C(),
+		type: t.type,
+		target: t.target ?? "",
+		text: t.text,
+		name: t.name,
+		addr: n.publicKey().address().toHex(),
+		ts: t.ts ?? Date.now()
+	}, a = {
+		...i,
 		sig: "0".repeat(130)
-	}, s = p.safeParse(o);
-	if (!s.success) throw new m("shape", b(s.error));
-	let c = v(o).byteLength;
-	if (c > 2048) throw new m("too-large", `${c} bytes, the cap is ${i}`);
+	}, o = _.safeParse(a);
+	if (!o.success) throw new v("shape", w(o.error));
+	let s = S(a).byteLength;
+	if (s > 2048) throw new v("too-large", `${s} bytes, the cap is ${c}`);
 	let l = {
-		...a,
-		sig: r.sign(_(a)).toHex()
+		...i,
+		sig: n.sign(x(i)).toHex()
 	};
 	return {
 		message: l,
-		bytes: v(l)
+		bytes: S(l)
 	};
 }
-function S(e) {
+function E(e) {
 	try {
-		return new t(e.sig).recoverPublicKey(_(e)).address().toHex() === e.addr;
+		return new a(e.sig).recoverPublicKey(x(e)).address().toHex() === e.addr;
 	} catch {
 		return !1;
 	}
 }
-function C(e) {
-	let t = p.safeParse(e);
-	return t.success ? S(t.data) ? {
+function D(e) {
+	let t = _.safeParse(e);
+	return t.success ? E(t.data) ? {
 		ok: !0,
 		message: t.data
 	} : {
@@ -124,18 +124,18 @@ function C(e) {
 	} : {
 		ok: !1,
 		reason: "shape",
-		detail: b(t.error)
+		detail: w(t.error)
 	};
 }
-function w(e) {
+function O(e) {
 	if (e.byteLength > 2048) return {
 		ok: !1,
 		reason: "too-large",
-		detail: `${e.byteLength} bytes, the cap is ${i}`
+		detail: `${e.byteLength} bytes, the cap is ${c}`
 	};
 	let t;
 	try {
-		t = g.decode(e);
+		t = b.decode(e);
 	} catch {
 		return {
 			ok: !1,
@@ -153,38 +153,38 @@ function w(e) {
 			detail: "the payload is not JSON"
 		};
 	}
-	return C(n);
+	return D(n);
 }
 //#endregion
 //#region src/message/entry.ts
-var T = 4096, E = n.string().regex(/^[0-9a-f]{64}([0-9a-f]{64})?$/, "expected a 64 or 128 hex character reference"), D = n.number().int().nonnegative().max(2 ** 53 - 1), O = n.strictObject({
-	ref: E,
-	toSeq: D
-}), k = n.strictObject({
-	v: n.literal(7),
-	seq: D,
-	at: D,
-	msg: p,
-	history: O.nullable()
-}), A = n.strictObject({
-	seq: D,
-	at: D,
-	msg: p
-}), j = n.strictObject({
-	v: n.literal(7),
-	topic: n.string().min(1),
-	fromSeq: D,
-	toSeq: D,
-	messages: n.array(n.unknown()),
-	prev: O.nullable()
+var k = 4096, A = o.string().regex(/^[0-9a-f]{64}([0-9a-f]{64})?$/, "expected a 64 or 128 hex character reference"), j = o.number().int().nonnegative().max(2 ** 53 - 1), M = o.strictObject({
+	ref: A,
+	toSeq: j
+}), N = o.strictObject({
+	v: o.literal(7),
+	seq: j,
+	at: j,
+	msg: _,
+	history: M.nullable()
+}), P = o.strictObject({
+	seq: j,
+	at: j,
+	msg: _
+}), F = o.strictObject({
+	v: o.literal(7),
+	topic: o.string().min(1),
+	fromSeq: j,
+	toSeq: j,
+	messages: o.array(o.unknown()),
+	prev: M.nullable()
 }).refine((e) => e.fromSeq <= e.toSeq, {
 	message: "fromSeq is after toSeq",
 	path: ["fromSeq"]
-}), M = new TextDecoder("utf-8", { fatal: !0 });
-function N(e) {
+}), I = new TextDecoder("utf-8", { fatal: !0 });
+function L(e) {
 	let t;
 	try {
-		t = M.decode(e);
+		t = I.decode(e);
 	} catch {
 		return {
 			ok: !1,
@@ -205,13 +205,13 @@ function N(e) {
 		};
 	}
 }
-function P(e) {
+function R(e) {
 	return e.issues.map((e) => `${e.path.join(".") || "value"}: ${e.message}`).join(", ");
 }
-function F(e, t, n) {
-	let r = N(e);
+function z(e, t, n) {
+	let r = L(e);
 	if (!r.ok) return r;
-	let i = k.safeParse(r.value);
+	let i = N.safeParse(r.value);
 	return i.success ? i.data.seq === t ? i.data.msg.topic === n ? {
 		ok: !0,
 		value: i.data
@@ -226,17 +226,17 @@ function F(e, t, n) {
 	} : {
 		ok: !1,
 		reason: "shape",
-		detail: P(i.error)
+		detail: R(i.error)
 	};
 }
-function I(e, t, n) {
-	let r = N(e);
+function B(e, t, n) {
+	let r = L(e);
 	if (!r.ok) return r;
-	let i = j.safeParse(r.value);
+	let i = F.safeParse(r.value);
 	if (!i.success) return {
 		ok: !1,
 		reason: "shape",
-		detail: P(i.error)
+		detail: R(i.error)
 	};
 	if (i.data.topic !== t || i.data.toSeq !== n.toSeq) return {
 		ok: !1,
@@ -245,7 +245,7 @@ function I(e, t, n) {
 	};
 	let { fromSeq: a, toSeq: o, prev: s } = i.data, c = [], l = 0;
 	for (let e of i.data.messages) {
-		let n = A.safeParse(e);
+		let n = P.safeParse(e);
 		n.success && n.data.seq >= a && n.data.seq <= o && n.data.msg.topic === t ? c.push(n.data) : l++;
 	}
 	return {
@@ -261,4 +261,48 @@ function I(e, t, n) {
 	};
 }
 //#endregion
-export { m as ChatMessageError, T as MAX_ENTRY_BYTES, i as MAX_MESSAGE_BYTES, s as MAX_NAME_CHARACTERS, o as MAX_TEXT_CHARACTERS, a as MAX_TOPIC_CHARACTERS, r as MESSAGE_VERSION, c as MessageType, p as chatMessageSchema, C as checkChatMessage, l as countCharacters, x as createChatMessage, v as encodeChatMessage, k as feedEntrySchema, S as hasValidSignature, j as historyFileSchema, O as historyLinkSchema, A as historyRowSchema, y as newMessageId, w as parseChatMessage, F as parseFeedEntry, I as parseHistoryFile, _ as signedBytes };
+//#region src/message/note.ts
+var V = 1, H = 2e3, U = 3e4, W = 256, G = o.strictObject({
+	v: o.literal(1),
+	newest: o.number().int().min(-1).max(2 ** 53 - 1),
+	writtenAt: o.number().int().nonnegative().max(2 ** 53 - 1)
+});
+function K(e) {
+	if (!Number.isInteger(e) || e <= 0) throw RangeError(`a note slot is a positive whole number of milliseconds, not ${e}`);
+}
+function q(e, t) {
+	return K(t), Math.floor(e / t);
+}
+function J(e, t) {
+	return K(t), (e + 1) * t;
+}
+function Y(e, t, n) {
+	return `${e}/note/${t}/${n}`;
+}
+function X(e, t, r) {
+	return n.fromString(Y(e, t, r));
+}
+function Z(n, r, a, o) {
+	let s = X(n, r, a);
+	return new i(e.keccak256(e.concat(s.toUint8Array(), new t(o).toUint8Array())));
+}
+var Q = new TextEncoder(), $ = new TextDecoder("utf-8", { fatal: !0 });
+function ee(e) {
+	let t = {
+		v: 1,
+		newest: e.newest,
+		writtenAt: e.writtenAt
+	};
+	return Q.encode(JSON.stringify(t));
+}
+function te(e) {
+	if (e.length > 256) return null;
+	try {
+		let t = G.safeParse(JSON.parse($.decode(e)));
+		return t.success ? t.data : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { v as ChatMessageError, U as DEFAULT_NOTE_HEARTBEAT_MS, H as DEFAULT_NOTE_SLOT_MS, k as MAX_ENTRY_BYTES, c as MAX_MESSAGE_BYTES, d as MAX_NAME_CHARACTERS, W as MAX_NOTE_BYTES, u as MAX_TEXT_CHARACTERS, l as MAX_TOPIC_CHARACTERS, s as MESSAGE_VERSION, f as MessageType, V as NOTE_VERSION, _ as chatMessageSchema, D as checkChatMessage, p as countCharacters, T as createChatMessage, S as encodeChatMessage, ee as encodeSlotNote, N as feedEntrySchema, E as hasValidSignature, F as historyFileSchema, M as historyLinkSchema, P as historyRowSchema, C as newMessageId, Z as noteAddress, X as noteIdentifier, Y as noteIdentifierText, J as noteSlotEnd, q as noteSlotOf, O as parseChatMessage, z as parseFeedEntry, B as parseHistoryFile, te as parseSlotNote, x as signedBytes, G as slotNoteSchema };

package/dist/notes.d.ts

@@ -0,0 +1,88 @@
+import { type SlotNote } from './message/index.js';
+import { type ChatSource } from './swarm.js';
+export interface NoteSettings {
+    /** The length of a time slot. Must be the server's, since it is part of every note's address. */
+    slotMs: number;
+    /** The longest the server goes without a note while a chat is active. Must be the server's. */
+    heartbeatMs: number;
+    /** How long after a slot ends, by the server's clock, its note is asked for. */
+    marginMs: number;
+    /** Notes read at once when looking back over several slots, newest first. */
+    scanBatch: number;
+    /** The furthest the clock correction goes either way. */
+    clockLimitMs: number;
+    /** The shortest wait between two reads of a note that came back missing, see `pacer.ts` for why. */
+    missingReadSpacingMs: number;
+}
+export declare const DEFAULT_NOTE_SETTINGS: NoteSettings;
+/** A note that was found, and the time slot it was found at. */
+export interface FoundNote {
+    slot: number;
+    note: SlotNote;
+}
+export type NoteSource = Required<Pick<ChatSource, 'readNote'>>;
+/** Whether a source can read notes, which a source written before notes existed cannot. */
+export declare function readsNotes(source: ChatSource): source is ChatSource & NoteSource;
+/**
+ * How far this viewer's clock runs ahead of the server's, in milliseconds, as far as reads can tell. A negative value
+ * is a clock that runs behind.
+ *
+ * Reads can only bound it from above. Whatever the server stamped, a note's `writtenAt` or an entry's `at`, it stamped
+ * before this viewer received it, so the viewer is at most `received - stamped` ahead. A read scheduled by this
+ * viewer's own clock says nothing more, since the same clock decides when it is sent. Learning that a clock runs
+ * ahead would need a read sent before the note existed, which is the request this whole scheme exists to avoid.
+ *
+ * So the correction trusts the local clock, `min(0, bound)`, which only ever moves a read earlier when the bound
+ * proves the clock runs behind, and never makes a read early. Once notes stop being found for longer than the
+ * heartbeat, the local clock is no longer trusted and every read waits out the whole bound. That is late by at most
+ * the freshest read's own delay and never early.
+ *
+ * A clock that runs behind sees every stamp exactly as old as it expects, since it reads everything as late as it
+ * runs behind, so no read proves it behind and its messages arrive that much late. Proving it would also take a read
+ * of something not yet written by the viewer's own clock.
+ */
+export declare class ClockCorrection {
+    private readonly limitMs;
+    private aheadAtMost;
+    private trusted;
+    constructor(limitMs: number);
+    observe(stampedMs: number, receivedMs: number): void;
+    /** Reads have stopped finding notes, which a clock that runs ahead of the server's explains. */
+    distrust(): void;
+    get isTrusted(): boolean;
+    get ms(): number;
+}
+/** Reads notes for the follower and the opening alike, so both share one clock correction and one count. */
+export declare class NoteReader {
+    private readonly source;
+    readonly now: () => number;
+    readonly clock: ClockCorrection;
+    /** Note reads that found a note, and those that found none, an unreadable chunk or a note that failed its check. */
+    readonly counts: {
+        found: number;
+        empty: number;
+    };
+    readonly settings: NoteSettings;
+    private readonly pacer;
+    constructor(source: NoteSource, settings: Partial<NoteSettings>, now: () => number);
+    /** The newest time slot whose note may be asked for at `now`: over, and the margin past, by the server's clock. */
+    lastReadableSlot(now?: number): number;
+    /** The local time from which slot `slot`'s note may be asked for. */
+    readableAt(slot: number): number;
+    /** How many slots back a reader looks for a note: one heartbeat and two slots, the longest a note can be apart. */
+    get lookBackSlots(): number;
+    /** How long a follower goes without finding a note before it stops trusting its clock. */
+    get silenceMs(): number;
+    /**
+     * One slot's note, or null when there is none to be had. Rejects only when the gateway fails. A note that came back
+     * missing is not asked for again within the spacing, which only an opening tried again or a clock found to run
+     * ahead would do, and is then null without asking.
+     */
+    read(slot: number): Promise<SlotNote | null>;
+    /**
+     * The newest note from slot `newest` back to slot `oldest`, read newest first, `scanBatch` at a time, stopping at
+     * the first batch that finds one. A note names the newest feed slot written by then, so the newest note found is the
+     * only one that matters.
+     */
+    scan(newest: number, oldest: number): Promise<FoundNote | null>;
+}

package/dist/pacer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The shortest wait between two reads of one address that came back missing: three reads a minute at most.
+ *
+ * Bee answers the first few reads of a chunk it cannot find 404, and puts every peer it asked on a skip list for that
+ * chunk for a minute (`ethersphere/bee`, `pkg/retrieval/retrieval.go`, `errSkip` and `skiplistDur = time.Minute`).
+ * Once no peer is left it answers 500 at once, because "no peer left" is not `storage.ErrNotFound`
+ * (`pkg/api/chunk.go`). A chunk written while its address is on that list stays unreadable on that node for up to a
+ * minute. Measured on swarm-dev on 2026-10-12: an address read every second for 20 s and then written was readable
+ * after 33 to 36 s, one nobody had asked for at once. About four reads of a missing address exhaust the list, so one
+ * read every twenty seconds stays under it.
+ */
+export declare const DEFAULT_MISSING_READ_SPACING_MS = 20000;
+/**
+ * Holds back a read of a slot whose address came back missing until `spacingMs` has passed since that answer. A slot
+ * that was found, or never read, may be read at once. A follower keeps one for feed slots and a note reader one for
+ * time slots.
+ */
+export declare class MissingReadPacer {
+    private readonly spacingMs;
+    private readonly now;
+    private readonly missedAt;
+    constructor(spacingMs: number, now: () => number);
+    /** The local time from which `slot` may be read again, which is in the past for an address not held back. */
+    readableAt(slot: number, now?: number): number;
+    mayRead(slot: number, now?: number): boolean;
+    missed(slot: number, now?: number): void;
+    found(slot: number): void;
+    clear(): void;
+    /** A miss recorded after `now` was recorded before the clock was set back, and holds nothing. */
+    private expired;
+}

package/dist/swarm.d.ts

@@ -17,6 +17,11 @@ export interface ChatSource {
     } | null>;
     /** A history file's bytes. Rejects when it cannot be read. */
     readFile(reference: string): Promise<Uint8Array>;
+    /**
+     * The payload of time slot `slot`'s note, or null when Bee answered that it is not there. Sorts its failures as
+     * `readSlot` does. A source without it follows the chat by polling the next slot, as before notes existed.
+     */
+    readNote?(slot: number): Promise<Uint8Array | null>;
 }
 /** Bee's head lookup did not answer within its timeout, which on a long chat or a busy gateway is ordinary. */
 export declare class HeadLookupTimeoutError extends Error {
@@ -59,8 +64,10 @@ export declare function readSlotThrough(index: number, read: () => Promise<Uint8
 /**
  * Reads a chat feed through bee-js's feed reader with an explicit index, which reads `GET /chunks/{address}` and
  * answers 404 only when the chunk could not be found, where `/soc/{owner}/{id}` answers 404 for any failure at all.
+ * Notes are read through bee-js's single owner chunk reader, which reads the same `GET /chunks/{address}` and checks
+ * the chunk is the owner's.
  */
-export declare function beeChatSource(bee: Bee, owner: string, chatTopic: string, timeouts: SwarmTimeouts): ChatSource;
+export declare function beeChatSource(bee: Bee, owner: string, chatTopic: string, timeouts: SwarmTimeouts, noteSlotMs?: number): ChatSource;
 /**
  * A batch id for a gateway that stamps what is written through it and ignores the one it is sent. Bee refuses a
  * write with no batch id at all, so something well formed has to go. The value 6.x sent, kept so a gateway that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarpunkltd/swarm-chat-js",
-  "version": "7.1.0",
+  "version": "7.3.0",
   "description": "JS library for chatting on Swarm",
   "keywords": [
     "chat",
@@ -36,15 +36,6 @@
       "require": "./dist/message.cjs"
     }
   },
-  "scripts": {
-    "build": "vite build && tsc -p tsconfig.build.json",
-    "prepack": "npm run build",
-    "lint": "oxlint --type-aware .",
-    "format": "oxfmt .",
-    "format:check": "oxfmt --check .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  },
   "dependencies": {
     "zod": "4.6.5"
   },
@@ -64,5 +55,12 @@
   "engines": {
     "node": ">=24"
   },
-  "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c"
-}
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "lint": "oxlint --type-aware .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}