@yappr/core 0.1.0

package/dist/channel.d.ts

@@ -0,0 +1,32 @@
+import { type ConnStatus, type SocketFactory } from "./connection.js";
+import { type Message } from "./log.js";
+import { type YapprStorage } from "./storage.js";
+export interface ChannelState {
+    messages: Message[];
+    status: ConnStatus;
+    unreadCount: number;
+    hasOlder: boolean;
+}
+export interface ChannelConfig {
+    channelId: string;
+    buildUrl: (since: number) => string;
+    selfUserId: string;
+    storage: YapprStorage;
+    createSocket?: SocketFactory;
+    genId?: () => string;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (h: unknown) => void;
+    random?: () => number;
+}
+export declare class Channel {
+    #private;
+    constructor(cfg: ChannelConfig);
+    init(): Promise<void>;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): ChannelState;
+    send(content: string): void;
+    loadOlder(): Promise<void>;
+    markRead(seq: number): void;
+    close(): void;
+}

package/dist/channel.js

@@ -0,0 +1,191 @@
+import { Connection } from "./connection.js";
+import { MessageLog } from "./log.js";
+import { Outbox } from "./outbox.js";
+import { UnreadTracker } from "./unread.js";
+import { storageKey } from "./storage.js";
+const PAGE_SIZE = 50;
+export class Channel {
+    #cfg;
+    #genId;
+    #now;
+    #log = new MessageLog();
+    #outbox;
+    #unread;
+    #conn;
+    #listeners = new Set();
+    #status = "disconnected";
+    #hasOlder = false;
+    #snapshot = null;
+    #dirty = true;
+    #loadingOlder = null;
+    constructor(cfg) {
+        this.#cfg = cfg;
+        this.#genId = cfg.genId ?? (() => crypto.randomUUID());
+        this.#now = cfg.now ?? (() => Date.now());
+        this.#outbox = new Outbox(cfg.storage, storageKey(cfg.channelId, "outbox"));
+        this.#unread = new UnreadTracker(cfg.storage, storageKey(cfg.channelId, "lastRead"));
+        this.#conn = new Connection({
+            getUrl: () => cfg.buildUrl(this.#log.newestSeq() ?? 0),
+            onOpen: () => this.#onOpen(),
+            onMessage: (m) => this.#onMessage(m),
+            onStatus: (s) => this.#onStatus(s),
+            createSocket: cfg.createSocket,
+            setTimer: cfg.setTimer,
+            clearTimer: cfg.clearTimer,
+            random: cfg.random,
+        });
+    }
+    async init() {
+        try {
+            await this.#outbox.load();
+            await this.#unread.load();
+            for (const e of this.#outbox.entries()) {
+                this.#log.addPending({
+                    status: "sending",
+                    id: e.clientMsgId,
+                    senderId: this.#cfg.selfUserId,
+                    content: e.content,
+                    createdAt: e.createdAt,
+                    kind: "user",
+                });
+            }
+        }
+        catch {
+            // storage failure is non-fatal — degrade to empty state but still connect
+        }
+        this.#bump();
+        this.#conn.connect();
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    getSnapshot() {
+        if (this.#dirty || this.#snapshot === null) {
+            this.#snapshot = {
+                messages: this.#log.messages(),
+                status: this.#status,
+                unreadCount: this.#unread.unreadCount(),
+                hasOlder: this.#hasOlder,
+            };
+            this.#dirty = false;
+        }
+        return this.#snapshot;
+    }
+    send(content) {
+        const id = this.#genId();
+        const createdAt = this.#now();
+        this.#log.addPending({ status: "sending", id, senderId: this.#cfg.selfUserId, content, createdAt, kind: "user" });
+        void this.#outbox.add({ clientMsgId: id, content, createdAt }).catch(() => { });
+        this.#conn.send(JSON.stringify({ type: "send", clientMsgId: id, content }));
+        this.#bump();
+    }
+    loadOlder() {
+        if (!this.#hasOlder)
+            return Promise.resolve();
+        if (this.#loadingOlder)
+            return this.#loadingOlder.promise;
+        const before = this.#log.oldestSeq();
+        if (before === undefined)
+            return Promise.resolve();
+        let resolve;
+        const promise = new Promise((r) => { resolve = r; });
+        this.#loadingOlder = { promise, resolve };
+        const sent = this.#conn.send(JSON.stringify({ type: "loadOlder", before, limit: PAGE_SIZE }));
+        if (!sent) {
+            this.#loadingOlder = null;
+            resolve();
+        }
+        return promise;
+    }
+    markRead(seq) {
+        const prev = this.#unread.lastRead();
+        if (seq <= prev)
+            return;
+        // #advance sets #lastRead synchronously before its internal await, so
+        // unreadCount() reflects the new value immediately after this call.
+        void this.#unread.markRead(seq).catch(() => { });
+        this.#conn.send(JSON.stringify({ type: "read", seq }));
+        this.#bump();
+    }
+    close() {
+        this.#conn.close();
+    }
+    #onStatus(s) {
+        this.#status = s;
+        if (s === "disconnected" && this.#loadingOlder) {
+            this.#loadingOlder.resolve();
+            this.#loadingOlder = null;
+        }
+        this.#bump();
+    }
+    #onOpen() {
+        for (const e of this.#outbox.entries()) {
+            this.#conn.send(JSON.stringify({ type: "send", clientMsgId: e.clientMsgId, content: e.content }));
+        }
+        const lastRead = this.#unread.lastRead();
+        if (lastRead > 0) {
+            this.#conn.send(JSON.stringify({ type: "read", seq: lastRead }));
+        }
+    }
+    #onMessage(msg) {
+        switch (msg.type) {
+            case "sync": {
+                this.#log.applyServer(msg.messages);
+                for (const m of msg.messages) {
+                    if (this.#outbox.has(m.id))
+                        void this.#outbox.remove(m.id).catch(() => { });
+                }
+                const newest = this.#log.newestSeq();
+                if (newest !== undefined)
+                    this.#unread.observe(newest);
+                void this.#unread.reconcileServer(msg.lastReadSeq).then((c) => { if (c)
+                    this.#bump(); }).catch(() => { });
+                this.#hasOlder = this.#computeHasOlder();
+                this.#bump();
+                break;
+            }
+            case "add": {
+                const isOwn = this.#outbox.has(msg.message.id);
+                this.#log.confirm(msg.message);
+                if (isOwn) {
+                    void this.#outbox.remove(msg.message.id).catch(() => { });
+                    void this.#unread.markRead(msg.message.seq).catch(() => { });
+                }
+                this.#unread.observe(msg.message.seq);
+                this.#bump();
+                break;
+            }
+            case "page": {
+                this.#log.prepend(msg.messages);
+                this.#hasOlder = msg.messages.length === 0 ? false : this.#computeHasOlder();
+                this.#loadingOlder?.resolve();
+                this.#loadingOlder = null;
+                this.#bump();
+                break;
+            }
+            case "read": {
+                void this.#unread.reconcileServer(msg.seq).then((c) => { if (c)
+                    this.#bump(); }).catch(() => { });
+                break;
+            }
+            case "error": {
+                if (msg.clientMsgId) {
+                    this.#log.markFailed(msg.clientMsgId);
+                    void this.#outbox.remove(msg.clientMsgId).catch(() => { });
+                    this.#bump();
+                }
+                break;
+            }
+        }
+    }
+    // Older history exists when the oldest message we hold isn't seq 1.
+    #computeHasOlder() {
+        return (this.#log.oldestSeq() ?? 1) > 1;
+    }
+    #bump() {
+        this.#dirty = true;
+        for (const l of this.#listeners)
+            l();
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import { type ChannelState } from "./channel.js";
+import { type YapprStorage } from "./storage.js";
+import type { SocketFactory } from "./connection.js";
+export interface YapprClientConfig {
+    url?: string;
+    tenantId: string;
+    key: string;
+    userId: string;
+    displayName?: string;
+    token?: string;
+    storage?: YapprStorage;
+    createSocket?: SocketFactory;
+    genId?: () => string;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (h: unknown) => void;
+    random?: () => number;
+}
+export interface ChannelHandle {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): ChannelState;
+    send(content: string): void;
+    loadOlder(): Promise<void>;
+    markRead(seq: number): void;
+    close(): void;
+}
+export interface YapprClient {
+    channel(channelId: string): ChannelHandle;
+    close(): void;
+}
+export declare function createClient(config: YapprClientConfig): YapprClient;

package/dist/client.js

@@ -0,0 +1,47 @@
+import { Channel } from "./channel.js";
+import { MemoryStorage } from "./storage.js";
+const DEFAULT_URL = "wss://api.yappr.sh";
+export function createClient(config) {
+    const storage = config.storage ?? new MemoryStorage();
+    const channels = new Map();
+    const buildUrl = (channelId, since) => {
+        const params = new URLSearchParams();
+        params.set("key", config.key);
+        if (config.userId)
+            params.set("userId", config.userId);
+        if (config.displayName)
+            params.set("displayName", config.displayName);
+        if (config.token)
+            params.set("token", config.token);
+        if (since > 0)
+            params.set("since", String(since));
+        return `${config.url ?? DEFAULT_URL}/parties/chat/${config.tenantId}:${channelId}?${params.toString()}`;
+    };
+    return {
+        channel(channelId) {
+            const existing = channels.get(channelId);
+            if (existing)
+                return existing;
+            const ch = new Channel({
+                channelId,
+                buildUrl: (since) => buildUrl(channelId, since),
+                selfUserId: config.userId,
+                storage,
+                createSocket: config.createSocket,
+                genId: config.genId,
+                now: config.now,
+                setTimer: config.setTimer,
+                clearTimer: config.clearTimer,
+                random: config.random,
+            });
+            channels.set(channelId, ch);
+            void ch.init();
+            return ch;
+        },
+        close() {
+            for (const ch of channels.values())
+                ch.close();
+            channels.clear();
+        },
+    };
+}

package/dist/connection.d.ts

@@ -0,0 +1,32 @@
+import { type ServerMessage } from "./protocol.js";
+export type ConnStatus = "connecting" | "connected" | "disconnected";
+export interface SocketLike {
+    send(d: string): void;
+    close(code?: number, reason?: string): void;
+    readyState: number;
+    onopen: (() => void) | null;
+    onclose: (() => void) | null;
+    onerror: (() => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+}
+export type SocketFactory = (url: string) => SocketLike;
+export interface ConnectionOptions {
+    getUrl: () => string;
+    onOpen: () => void;
+    onMessage: (m: ServerMessage) => void;
+    onStatus: (s: ConnStatus) => void;
+    createSocket?: SocketFactory;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (h: unknown) => void;
+    random?: () => number;
+}
+export declare class Connection {
+    #private;
+    constructor(o: ConnectionOptions);
+    status(): ConnStatus;
+    connect(): void;
+    send(d: string): boolean;
+    close(): void;
+}

package/dist/connection.js

@@ -0,0 +1,85 @@
+import { parseServerMessage } from "./protocol.js";
+const OPEN = 1;
+export class Connection {
+    #o;
+    #socket = null;
+    #status = "disconnected";
+    #attempt = 0;
+    #closing = false;
+    #timer = null;
+    constructor(o) {
+        this.#o = {
+            getUrl: o.getUrl,
+            onOpen: o.onOpen,
+            onMessage: o.onMessage,
+            onStatus: o.onStatus,
+            createSocket: o.createSocket ?? ((url) => new WebSocket(url)),
+            setTimer: o.setTimer ?? ((fn, ms) => setTimeout(fn, ms)),
+            clearTimer: o.clearTimer ?? ((h) => clearTimeout(h)),
+            random: o.random ?? Math.random,
+        };
+    }
+    status() {
+        return this.#status;
+    }
+    connect() {
+        if (this.#timer !== null) {
+            this.#o.clearTimer(this.#timer);
+            this.#timer = null;
+        }
+        this.#closing = false;
+        this.#setStatus("connecting");
+        const socket = this.#o.createSocket(this.#o.getUrl());
+        this.#socket = socket;
+        socket.onopen = () => {
+            this.#attempt = 0;
+            this.#setStatus("connected");
+            this.#o.onOpen();
+        };
+        socket.onmessage = (ev) => {
+            if (typeof ev.data !== "string")
+                return;
+            const msg = parseServerMessage(ev.data);
+            if (msg)
+                this.#o.onMessage(msg);
+        };
+        socket.onclose = () => this.#onDrop();
+        socket.onerror = () => this.#onDrop();
+    }
+    send(d) {
+        if (this.#socket && this.#socket.readyState === OPEN) {
+            this.#socket.send(d);
+            return true;
+        }
+        return false;
+    }
+    close() {
+        this.#closing = true;
+        if (this.#timer !== null) {
+            this.#o.clearTimer(this.#timer);
+            this.#timer = null;
+        }
+        this.#socket?.close();
+        this.#setStatus("disconnected");
+    }
+    #onDrop() {
+        if (this.#closing || this.#timer !== null)
+            return;
+        this.#setStatus("disconnected");
+        const ms = this.#delay(this.#attempt++);
+        this.#timer = this.#o.setTimer(() => {
+            this.#timer = null;
+            this.connect();
+        }, ms);
+    }
+    #delay(attempt) {
+        const base = Math.min(15000, 500 * 2 ** attempt);
+        return base / 2 + this.#o.random() * (base / 2);
+    }
+    #setStatus(s) {
+        if (this.#status === s)
+            return;
+        this.#status = s;
+        this.#o.onStatus(s);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./protocol.js";
+export * from "./storage.js";
+export { Outbox, type OutboxEntry } from "./outbox.js";
+export { MessageLog, type Message, type PendingMessage } from "./log.js";
+export { UnreadTracker } from "./unread.js";
+export { Connection, type ConnStatus, type SocketLike, type SocketFactory } from "./connection.js";
+export { Channel, type ChannelState, type ChannelConfig } from "./channel.js";
+export { createClient, type YapprClient, type YapprClientConfig, type ChannelHandle, } from "./client.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./protocol.js";
+export * from "./storage.js";
+export { Outbox } from "./outbox.js";
+export { MessageLog } from "./log.js";
+export { UnreadTracker } from "./unread.js";
+export { Connection } from "./connection.js";
+export { Channel } from "./channel.js";
+export { createClient, } from "./client.js";

package/dist/log.d.ts

@@ -0,0 +1,23 @@
+import type { Envelope } from "./protocol.js";
+export interface PendingMessage {
+    status: "sending" | "failed";
+    id: string;
+    senderId: string;
+    content: string;
+    createdAt: number;
+    kind: "user";
+}
+export type Message = (Envelope & {
+    status: "sent";
+}) | PendingMessage;
+export declare class MessageLog {
+    #private;
+    addPending(p: PendingMessage): void;
+    confirm(env: Envelope): void;
+    applyServer(envs: Envelope[]): void;
+    prepend(envs: Envelope[]): void;
+    markFailed(id: string): void;
+    oldestSeq(): number | undefined;
+    newestSeq(): number | undefined;
+    messages(): Message[];
+}

package/dist/log.js

@@ -0,0 +1,59 @@
+export class MessageLog {
+    #confirmed = new Map(); // seq -> envelope
+    #confirmedIds = new Set();
+    #pending = [];
+    // Seq bounds tracked incrementally; confirmed rows are never removed, so
+    // these stay valid without rescanning the map on every read.
+    #minSeq;
+    #maxSeq;
+    addPending(p) {
+        if (this.#confirmedIds.has(p.id))
+            return;
+        if (this.#pending.some((x) => x.id === p.id))
+            return;
+        this.#pending.push(p);
+    }
+    confirm(env) {
+        this.#removePending(env.id);
+        this.#upsert(env);
+    }
+    applyServer(envs) {
+        for (const e of envs) {
+            this.#removePending(e.id);
+            this.#upsert(e);
+        }
+    }
+    prepend(envs) {
+        for (const e of envs)
+            if (!this.#confirmedIds.has(e.id))
+                this.#upsert(e);
+    }
+    markFailed(id) {
+        const p = this.#pending.find((x) => x.id === id);
+        if (p)
+            p.status = "failed";
+    }
+    oldestSeq() {
+        return this.#minSeq;
+    }
+    newestSeq() {
+        return this.#maxSeq;
+    }
+    messages() {
+        const confirmed = [...this.#confirmed.values()]
+            .sort((a, b) => a.seq - b.seq)
+            .map((e) => ({ ...e, status: "sent" }));
+        return [...confirmed, ...this.#pending];
+    }
+    #upsert(env) {
+        this.#confirmed.set(env.seq, env);
+        this.#confirmedIds.add(env.id);
+        if (this.#minSeq === undefined || env.seq < this.#minSeq)
+            this.#minSeq = env.seq;
+        if (this.#maxSeq === undefined || env.seq > this.#maxSeq)
+            this.#maxSeq = env.seq;
+    }
+    #removePending(id) {
+        this.#pending = this.#pending.filter((x) => x.id !== id);
+    }
+}

package/dist/outbox.d.ts

@@ -0,0 +1,15 @@
+import type { YapprStorage } from "./storage.js";
+export interface OutboxEntry {
+    clientMsgId: string;
+    content: string;
+    createdAt: number;
+}
+export declare class Outbox {
+    #private;
+    constructor(storage: YapprStorage, key: string);
+    load(): Promise<void>;
+    entries(): OutboxEntry[];
+    has(id: string): boolean;
+    add(entry: OutboxEntry): Promise<void>;
+    remove(id: string): Promise<void>;
+}

package/dist/outbox.js

@@ -0,0 +1,46 @@
+function isEntry(x) {
+    return (typeof x === "object" && x !== null &&
+        typeof x.clientMsgId === "string" &&
+        typeof x.content === "string" &&
+        typeof x.createdAt === "number");
+}
+export class Outbox {
+    #storage;
+    #key;
+    #entries = [];
+    constructor(storage, key) {
+        this.#storage = storage;
+        this.#key = key;
+    }
+    async load() {
+        const raw = await this.#storage.get(this.#key);
+        if (!raw)
+            return;
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                this.#entries = parsed.filter(isEntry);
+        }
+        catch {
+            this.#entries = [];
+        }
+    }
+    entries() {
+        return this.#entries;
+    }
+    has(id) {
+        return this.#entries.some((e) => e.clientMsgId === id);
+    }
+    async add(entry) {
+        if (!this.has(entry.clientMsgId))
+            this.#entries.push(entry);
+        await this.#persist();
+    }
+    async remove(id) {
+        this.#entries = this.#entries.filter((e) => e.clientMsgId !== id);
+        await this.#persist();
+    }
+    async #persist() {
+        await this.#storage.set(this.#key, JSON.stringify(this.#entries));
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,46 @@
+export type MessageKind = "user";
+export interface Envelope {
+    seq: number;
+    id: string;
+    senderId: string;
+    content: string;
+    createdAt: number;
+    kind: MessageKind;
+}
+export type ClientMessage = {
+    type: "send";
+    clientMsgId: string;
+    content: string;
+} | {
+    type: "read";
+    seq: number;
+} | {
+    type: "loadOlder";
+    before: number;
+    limit: number;
+};
+export type ParsedClient = ClientMessage | {
+    type: "__unknown__";
+};
+export type ServerMessage = {
+    type: "sync";
+    messages: Envelope[];
+    hasGap: boolean;
+    lastReadSeq: number;
+} | {
+    type: "add";
+    message: Envelope;
+} | {
+    type: "page";
+    messages: Envelope[];
+} | {
+    type: "read";
+    seq: number;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+    clientMsgId?: string;
+};
+export declare function parseClientMessage(raw: string): ParsedClient;
+export declare function parseServerMessage(raw: string): ServerMessage | null;

package/dist/protocol.js

@@ -0,0 +1,77 @@
+function isEnvelope(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const e = x;
+    return (typeof e.seq === "number" && typeof e.id === "string" &&
+        typeof e.senderId === "string" && typeof e.content === "string" &&
+        typeof e.createdAt === "number" && typeof e.kind === "string");
+}
+function asObject(raw) {
+    const data = JSON.parse(raw); // may throw — caller decides
+    if (typeof data !== "object" || data === null)
+        throw new Error("not_an_object");
+    return data;
+}
+export function parseClientMessage(raw) {
+    let data;
+    try {
+        data = asObject(raw);
+    }
+    catch {
+        throw new Error("invalid_json");
+    }
+    switch (data.type) {
+        case "send":
+            if (typeof data.clientMsgId !== "string" || typeof data.content !== "string")
+                throw new Error("invalid_client_message");
+            return { type: "send", clientMsgId: data.clientMsgId, content: data.content };
+        case "read":
+            if (typeof data.seq !== "number")
+                throw new Error("invalid_client_message");
+            return { type: "read", seq: data.seq };
+        case "loadOlder":
+            if (typeof data.before !== "number" || typeof data.limit !== "number")
+                throw new Error("invalid_client_message");
+            return { type: "loadOlder", before: data.before, limit: data.limit };
+        default:
+            return { type: "__unknown__" }; // forward-compat: ignore unknown types
+    }
+}
+export function parseServerMessage(raw) {
+    let data;
+    try {
+        data = asObject(raw);
+    }
+    catch {
+        return null;
+    }
+    switch (data.type) {
+        case "sync":
+            if (Array.isArray(data.messages) && data.messages.every(isEnvelope) && typeof data.hasGap === "boolean" && typeof data.lastReadSeq === "number")
+                return { type: "sync", messages: data.messages, hasGap: data.hasGap, lastReadSeq: data.lastReadSeq };
+            return null;
+        case "add":
+            if (isEnvelope(data.message))
+                return { type: "add", message: data.message };
+            return null;
+        case "page":
+            if (Array.isArray(data.messages) && data.messages.every(isEnvelope))
+                return { type: "page", messages: data.messages };
+            return null;
+        case "read":
+            if (typeof data.seq === "number")
+                return { type: "read", seq: data.seq };
+            return null;
+        case "error":
+            if (typeof data.code === "string" && typeof data.message === "string")
+                return {
+                    type: "error",
+                    code: data.code,
+                    message: data.message,
+                    ...(typeof data.clientMsgId === "string" ? { clientMsgId: data.clientMsgId } : {}),
+                };
+            return null;
+        default:
+            return null; // forward-compat: ignore unknown types
+    }
+}

package/dist/storage.d.ts

@@ -0,0 +1,12 @@
+export interface YapprStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+export declare class MemoryStorage implements YapprStorage {
+    #private;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+export declare function storageKey(channelId: string, name: string): string;

package/dist/storage.js

@@ -0,0 +1,15 @@
+export class MemoryStorage {
+    #m = new Map();
+    async get(key) {
+        return this.#m.has(key) ? this.#m.get(key) : null;
+    }
+    async set(key, value) {
+        this.#m.set(key, value);
+    }
+    async remove(key) {
+        this.#m.delete(key);
+    }
+}
+export function storageKey(channelId, name) {
+    return `yappr:${channelId}:${name}`;
+}

package/dist/unread.d.ts

@@ -0,0 +1,11 @@
+import type { YapprStorage } from "./storage.js";
+export declare class UnreadTracker {
+    #private;
+    constructor(storage: YapprStorage, key: string);
+    load(): Promise<void>;
+    lastRead(): number;
+    observe(seq: number): void;
+    unreadCount(): number;
+    markRead(seq: number): Promise<boolean>;
+    reconcileServer(seq: number): Promise<boolean>;
+}

package/dist/unread.js

@@ -0,0 +1,39 @@
+export class UnreadTracker {
+    #storage;
+    #key;
+    #lastRead = 0;
+    #highest = 0;
+    constructor(storage, key) {
+        this.#storage = storage;
+        this.#key = key;
+    }
+    async load() {
+        const raw = await this.#storage.get(this.#key);
+        const n = raw ? parseInt(raw, 10) : NaN;
+        if (Number.isFinite(n))
+            this.#lastRead = n;
+    }
+    lastRead() {
+        return this.#lastRead;
+    }
+    observe(seq) {
+        if (seq > this.#highest)
+            this.#highest = seq;
+    }
+    unreadCount() {
+        return Math.max(0, this.#highest - this.#lastRead);
+    }
+    async markRead(seq) {
+        return this.#advance(seq);
+    }
+    async reconcileServer(seq) {
+        return this.#advance(seq);
+    }
+    async #advance(seq) {
+        if (seq <= this.#lastRead)
+            return false;
+        this.#lastRead = seq;
+        await this.#storage.set(this.#key, String(this.#lastRead));
+        return true;
+    }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@yappr/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  }
+}