@solarpunkltd/swarm-chat-js 6.2.7 → 7.0.0

package/dist/message/entry.d.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+/**
+ * What the server writes: one feed entry per message at indices 0, 1, 2 and on, and one history file per chat that
+ * the entries point to. The server builds these and the reader checks their shape. The reader does not check each
+ * message's signature, because the server checked it before publishing.
+ */
+/** A feed entry is always one chunk, so bee-js never wraps it. */
+export declare const MAX_ENTRY_BYTES = 4096;
+export declare const historyLinkSchema: z.ZodObject<{
+    ref: z.ZodString;
+    toSeq: z.ZodNumber;
+}, z.core.$strict>;
+export type HistoryLink = z.infer<typeof historyLinkSchema>;
+export declare const feedEntrySchema: z.ZodObject<{
+    v: z.ZodLiteral<7>;
+    seq: z.ZodNumber;
+    at: z.ZodNumber;
+    msg: z.ZodObject<{
+        v: z.ZodLiteral<7>;
+        topic: z.ZodString;
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            reaction: "reaction";
+            text: "text";
+            thread: "thread";
+        }>;
+        target: z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>;
+        text: z.ZodString;
+        name: z.ZodString;
+        addr: z.ZodString;
+        ts: z.ZodNumber;
+        sig: z.ZodString;
+    }, z.core.$strict>;
+    history: z.ZodNullable<z.ZodObject<{
+        ref: z.ZodString;
+        toSeq: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type FeedEntry = z.infer<typeof feedEntrySchema>;
+export declare const historyRowSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    at: z.ZodNumber;
+    msg: z.ZodObject<{
+        v: z.ZodLiteral<7>;
+        topic: z.ZodString;
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            reaction: "reaction";
+            text: "text";
+            thread: "thread";
+        }>;
+        target: z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>;
+        text: z.ZodString;
+        name: z.ZodString;
+        addr: z.ZodString;
+        ts: z.ZodNumber;
+        sig: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type HistoryRow = z.infer<typeof historyRowSchema>;
+/** A row that fails its shape is left out and counted, so one bad row never hides the rest of the file. */
+export declare const historyFileSchema: z.ZodObject<{
+    v: z.ZodLiteral<7>;
+    topic: z.ZodString;
+    fromSeq: z.ZodNumber;
+    toSeq: z.ZodNumber;
+    messages: z.ZodArray<z.ZodUnknown>;
+    prev: z.ZodNullable<z.ZodObject<{
+        ref: z.ZodString;
+        toSeq: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export interface HistoryFile {
+    topic: string;
+    fromSeq: number;
+    toSeq: number;
+    rows: HistoryRow[];
+    prev: HistoryLink | null;
+    /** Rows left out because they failed their shape, lay outside fromSeq to toSeq, or belonged to another chat. */
+    skipped: number;
+}
+export type ReadRefusal = 'not-utf8' | 'not-json' | 'shape' | 'mismatch';
+export type ReadCheck<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: ReadRefusal;
+    detail: string;
+};
+/**
+ * Reads the entry at feed index `index` of chat `topic`. An entry is refused when its `seq` is not that index or its
+ * message belongs to another chat, since either would put a message in the wrong place.
+ */
+export declare function parseFeedEntry(payload: Uint8Array, index: number, topic: string): ReadCheck<FeedEntry>;
+/** Reads a history file of chat `topic` that `link` pointed to. */
+export declare function parseHistoryFile(payload: Uint8Array, topic: string, link: HistoryLink): ReadCheck<HistoryFile>;

package/dist/message/index.d.ts

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

package/dist/message/message.d.ts

@@ -0,0 +1,90 @@
+import { PrivateKey } from '@ethersphere/bee-js';
+import { z } from 'zod';
+/**
+ * The chat message of version 7: what a browser sends as a GSOC payload, what the server verifies before it
+ * publishes, and what every feed entry carries back as `msg`. This module is the only place its bytes are built,
+ * signed, checked and read, and the server imports it from here rather than keeping a copy.
+ */
+export declare const MESSAGE_VERSION = 7;
+/** Measured on the UTF-8 of the whole JSON object, on top of the per-field caps. */
+export declare const MAX_MESSAGE_BYTES = 2048;
+export declare const MAX_TOPIC_CHARACTERS = 128;
+export declare const MAX_TEXT_CHARACTERS = 500;
+export declare const MAX_NAME_CHARACTERS = 20;
+export declare const MessageType: {
+    readonly TEXT: 'text';
+    readonly THREAD: 'thread';
+    readonly REACTION: 'reaction';
+};
+export type MessageType = (typeof MessageType)[keyof typeof MessageType];
+/**
+ * Characters are counted as Unicode code points, never as UTF-16 units, so an emoji outside the basic plane counts
+ * once. A composer that shows a count uses this function, so it and the check agree.
+ */
+export declare function countCharacters(value: string): number;
+export declare const chatMessageSchema: z.ZodObject<{
+    v: z.ZodLiteral<7>;
+    topic: z.ZodString;
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        reaction: "reaction";
+        text: "text";
+        thread: "thread";
+    }>;
+    target: z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>;
+    text: z.ZodString;
+    name: z.ZodString;
+    addr: z.ZodString;
+    ts: z.ZodNumber;
+    sig: z.ZodString;
+}, z.core.$strict>;
+export type ChatMessage = z.infer<typeof chatMessageSchema>;
+export type UnsignedChatMessage = Omit<ChatMessage, 'sig'>;
+export type ChatMessageRefusal = 'too-large' | 'not-utf8' | 'not-json' | 'shape' | 'signature';
+export type ChatMessageCheck = {
+    ok: true;
+    message: ChatMessage;
+} | {
+    ok: false;
+    reason: ChatMessageRefusal;
+    detail: string;
+};
+export declare class ChatMessageError extends Error {
+    readonly reason: ChatMessageRefusal;
+    constructor(reason: ChatMessageRefusal, detail: string);
+}
+/** The exact bytes a sender signs and a verifier recovers the signer from. Their order is the contract. */
+export declare function signedBytes(message: UnsignedChatMessage): Uint8Array;
+/** The payload bytes, with the fields in the contract's order so two senders of one message send one payload. */
+export declare function encodeChatMessage(message: ChatMessage): Uint8Array;
+export declare function newMessageId(): string;
+export interface ChatMessageDraft {
+    topic: string;
+    type: MessageType;
+    /** The id a thread reply or a reaction refers to. Left out for a text message. */
+    target?: string;
+    text: string;
+    name: string;
+    /** Made fresh when left out. Given only to rebuild a message whose bytes must not change. */
+    id?: string;
+    /** The sender's clock in milliseconds, `Date.now()` when left out. */
+    ts?: number;
+}
+export interface SignedChatMessage {
+    message: ChatMessage;
+    bytes: Uint8Array;
+}
+/**
+ * Builds and signs a message, and throws a ChatMessageError before signing anything that the server would refuse:
+ * a field outside its cap, or a payload over MAX_MESSAGE_BYTES.
+ */
+export declare function createChatMessage(privateKey: PrivateKey | Uint8Array | string, draft: ChatMessageDraft): SignedChatMessage;
+/** Whether `sig` was made over this message's signed bytes by the key behind `addr`. */
+export declare function hasValidSignature(message: ChatMessage): boolean;
+/** Checks a message that arrived as an object, its shape and its signature. */
+export declare function checkChatMessage(value: unknown): ChatMessageCheck;
+/**
+ * Checks a message as it arrived on the wire: the byte cap on the raw payload, then UTF-8, JSON, the shape and the
+ * signature. Never throws, since the server calls it on whatever anybody writes to the chat's GSOC address.
+ */
+export declare function parseChatMessage(payload: Uint8Array): ChatMessageCheck;

package/dist/message.cjs

@@ -0,0 +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;

package/dist/message.js

@@ -0,0 +1,264 @@
+import { PrivateKey as e, Signature as t } from "@ethersphere/bee-js";
+import { z as n } from "zod";
+//#region src/message/message.ts
+var r = 7, i = 2048, a = 128, o = 500, s = 20, c = {
+	TEXT: "text",
+	THREAD: "thread",
+	REACTION: "reaction"
+};
+function l(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 d(e, t) {
+	return n.string().refine((n) => {
+		let r = l(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
+	]),
+	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 === ""), {
+	message: "a text message has no target, a thread reply or a reaction names one",
+	path: ["target"]
+}), m = 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([
+		e.v,
+		e.topic,
+		e.id,
+		e.type,
+		e.target,
+		e.text,
+		e.name,
+		e.addr,
+		e.ts
+	]));
+}
+function v(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 h.encode(JSON.stringify(t));
+}
+function y() {
+	let e = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16));
+	return Array.from(e, (e) => e.toString(16).padStart(2, "0")).join("");
+}
+function b(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 = {
+		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,
+		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}`);
+	let l = {
+		...a,
+		sig: r.sign(_(a)).toHex()
+	};
+	return {
+		message: l,
+		bytes: v(l)
+	};
+}
+function S(e) {
+	try {
+		return new t(e.sig).recoverPublicKey(_(e)).address().toHex() === e.addr;
+	} catch {
+		return !1;
+	}
+}
+function C(e) {
+	let t = p.safeParse(e);
+	return t.success ? S(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: b(t.error)
+	};
+}
+function w(e) {
+	if (e.byteLength > 2048) return {
+		ok: !1,
+		reason: "too-large",
+		detail: `${e.byteLength} bytes, the cap is ${i}`
+	};
+	let t;
+	try {
+		t = g.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 C(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()
+}).refine((e) => e.fromSeq <= e.toSeq, {
+	message: "fromSeq is after toSeq",
+	path: ["fromSeq"]
+}), M = new TextDecoder("utf-8", { fatal: !0 });
+function N(e) {
+	let t;
+	try {
+		t = M.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 P(e) {
+	return e.issues.map((e) => `${e.path.join(".") || "value"}: ${e.message}`).join(", ");
+}
+function F(e, t, n) {
+	let r = N(e);
+	if (!r.ok) return r;
+	let i = k.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: P(i.error)
+	};
+}
+function I(e, t, n) {
+	let r = N(e);
+	if (!r.ok) return r;
+	let i = j.safeParse(r.value);
+	if (!i.success) return {
+		ok: !1,
+		reason: "shape",
+		detail: P(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 = A.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
+		}
+	};
+}
+//#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 };

package/dist/sender.d.ts

@@ -0,0 +1,62 @@
+import type { PrivateKey } from '@ethersphere/bee-js';
+import { type ChatMessage, type ChatMessageDraft } from './message/index.js';
+/** Writes one payload to the chat's GSOC address. Rejects when the write did not reach the node. */
+export type GsocWrite = (payload: Uint8Array) => Promise<void>;
+export interface SenderSettings {
+    /** How long a written message may go unseen on the chat feed before its identical bytes are written again. */
+    resendAfterMs: number;
+    /** Resends after the first write, before the message is failed. */
+    maxResends: number;
+    /** Taps on one reaction inside this window become one net toggle. */
+    reactionWindowMs: number;
+    /**
+     * Whether the reader can see the chat feed now. While it cannot, the resends and the give-up wait, since a message
+     * the server published would be failed only because this viewer could not see it.
+     */
+    isLive: () => boolean;
+}
+export declare const DEFAULT_SENDER_SETTINGS: SenderSettings;
+export interface SenderEvents {
+    /** Built and signed, and about to be written. */
+    pending(message: ChatMessage): void;
+    /** The first write that the node accepted. */
+    written(message: ChatMessage): void;
+    /** Every resend used up, or a write refused in a way a resend cannot mend. `retry` sends it again. */
+    failed(message: ChatMessage, error: unknown): void;
+    /** Read back from the chat feed. */
+    confirmed(message: ChatMessage): void;
+}
+export type SendDraft = Omit<ChatMessageDraft, 'name' | 'ts' | 'id'>;
+/**
+ * Sends signed messages as GSOC writes and keeps each one pending until the chat feed shows it. A pending message is
+ * written again with the identical bytes, so the server can tell a resend from a new message by its id.
+ */
+export declare class Sender {
+    private readonly key;
+    private readonly name;
+    private readonly write;
+    private readonly events;
+    private readonly settings;
+    private readonly outgoing;
+    private readonly reactions;
+    private stopped;
+    constructor(key: PrivateKey, name: string, write: GsocWrite, events: SenderEvents, settings?: SenderSettings);
+    get address(): string;
+    /** Builds, signs and writes a message. Throws a ChatMessageError, and writes nothing, for one the server would refuse. */
+    send(draft: SendDraft): ChatMessage;
+    /**
+     * One tap on a reaction. A reaction sent again takes it back, so taps inside one window cancel in pairs and only an
+     * odd count sends anything, once, when the window closes.
+     */
+    react(topic: string, target: string, emoji: string): void;
+    /** Called for every message the chat feed shows. Ends the wait for one this sender wrote. */
+    confirm(message: ChatMessage): void;
+    /** Writes a failed or still pending message again, with the same bytes, and starts its resends over. */
+    retry(id: string): boolean;
+    isPending(id: string): boolean;
+    /** Cancels every resend and every open reaction window. Messages still pending stay unconfirmed. */
+    stop(): void;
+    private attempt;
+    private scheduleNext;
+    private clearTimer;
+}

package/dist/swarm.d.ts

@@ -0,0 +1,74 @@
+import { type Bee } from '@ethersphere/bee-js';
+import type { GsocWrite } from './sender.js';
+/** Everything the reader asks of Swarm, so the reader can be driven by a fake in tests. */
+export interface ChatSource {
+    /**
+     * The payload at one feed index, or null when Bee answered 404. Rejects with an UnreadableSlotError when a chunk was
+     * served that fails its own check, and with anything else when the gateway failed.
+     */
+    readSlot(index: number): Promise<Uint8Array | null>;
+    /**
+     * Bee's head lookup: the newest index it found and its payload, or null when it answered that nothing is there.
+     * Rejects with a HeadLookupTimeoutError when it ran out of time, and with anything else when the gateway failed.
+     */
+    readHead(): Promise<{
+        index: number;
+        payload: Uint8Array;
+    } | null>;
+    /** A history file's bytes. Rejects when it cannot be read. */
+    readFile(reference: string): Promise<Uint8Array>;
+}
+/** 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 {
+    constructor(options: {
+        cause: unknown;
+    });
+}
+/**
+ * A slot the gateway served whose chunk failed its own check, such as a signature that is not the owner's. A fact
+ * about that one slot and not about the gateway, so it never holds the reader back from the slots after it.
+ */
+export declare class UnreadableSlotError extends Error {
+    readonly index: number;
+    constructor(index: number, options: {
+        cause: unknown;
+    });
+}
+export interface SwarmTimeouts {
+    /** A read of one feed slot. */
+    slotReadMs: number;
+    /** The head lookup and a history file download, which are slower by nature. */
+    feedReadMs: number;
+    /** One GSOC write. */
+    writeMs: number;
+}
+/**
+ * Whether Bee said the chunk is not there. A 404 means no peer gave it within Bee's retry budget, which at the live
+ * edge is the ordinary "not written yet" and elsewhere a slow read. A Bee 2.6 cluster answers 500 on `GET /chunks` for
+ * a slot never written, measured on the test bed, so a 500 counts too, as bee-js's own `isRetrievable` counts it.
+ * Neither ever means the chat has ended, and a read that is wrong about "not there" is asked again on the next poll.
+ * Every other failure, a timeout, an abort, a refused connection or a 502, 503 or 504, is the gateway failing.
+ */
+export declare function isAbsent(error: unknown): boolean;
+/**
+ * One slot read, sorted into what it means: the payload, null for a slot that is not there, an UnreadableSlotError for
+ * a chunk served that fails its own check, and a rejection for the gateway failing. Shared by the Bee reader and the
+ * tests' fake, so both sort failures the same way.
+ */
+export declare function readSlotThrough(index: number, read: () => Promise<Uint8Array>): Promise<Uint8Array | null>;
+/**
+ * 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.
+ */
+export declare function beeChatSource(bee: Bee, owner: string, chatTopic: string, timeouts: SwarmTimeouts): 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
+ * recognises it keeps doing so.
+ */
+export declare const GATEWAY_STAMPS_ITSELF: string;
+/**
+ * Writes to the chat's inbox: one GSOC address shared by every chat, signed with the mined key every sender holds.
+ * Never deferred and never tagged, so each write is pushed at once and two different messages never collide.
+ */
+export declare function beeGsocWrite(bee: Bee, stamp: string, gsocKey: string, gsocTopic: string, timeouts: SwarmTimeouts): GsocWrite;