@sansavision/yousaid 0.0.0-stage → 0.2.0

package/dist/proof.js

@@ -0,0 +1,278 @@
+import { uploadProofMedia } from "./proof-upload.js";
+function renderQuery(options) {
+    const params = new URLSearchParams();
+    if (options.bucket !== undefined)
+        params.set("b", String(options.bucket === "random" ? Math.floor(Math.random() * 100) : Math.max(0, Math.min(99, Math.floor(options.bucket)))));
+    const context = options.context ?? {};
+    const pairs = [["slot", "ctx_slot"], ["audience", "ctx_segment"], ["product", "ctx_product"], ["locale", "ctx_locale"], ["page", "ctx_page"]];
+    for (const [key, param] of pairs)
+        if (context[key])
+            params.set(param, String(context[key]).slice(0, key === "page" ? 200 : 48));
+    const query = params.toString();
+    return query ? `?${query}` : "";
+}
+function origin(endpoint) {
+    return new URL(endpoint ?? "https://yousaid.dev", "https://yousaid.dev").origin;
+}
+/**
+ * Fetches the eligibility-gated render manifest for a placement. No cookies are sent.
+ * @experimental
+ */
+export async function fetchProofRender(placementId, options = {}) {
+    if (!/^ppl_[0-9a-f]{32}$/.test(placementId))
+        throw new Error("Invalid placement id.");
+    const response = await (options.fetch ?? globalThis.fetch)(`${origin(options.endpoint)}/api/public/proof/render/${placementId}${renderQuery(options)}`, { credentials: "omit", signal: options.signal });
+    if (!response.ok)
+        throw new Error(`Proof render failed (${response.status}).`);
+    const data = await response.json();
+    if (data.schema !== "yousaid-proof-render-v1")
+        throw new Error("Unsupported proof render schema.");
+    return data;
+}
+/**
+ * A signed snapshot may be shown as a fallback only until it expires (the revocation SLA window).
+ * @experimental
+ */
+export function isRenderFresh(render, now = Date.now()) {
+    return Date.parse(render.expiresAt) > now;
+}
+/** Must match RENDER_PUBLIC_SIGNATURE_PREFIX in lib/proof-publish/render.ts. */
+const RENDER_SIGNATURE_PREFIX = "yousaid-proof-render:";
+const keySets = new Map();
+/**
+ * Published proof keys (current and previous Ed25519 keys) from the same
+ * first-party origin as the render API, never a third party. Cached per origin
+ * for the page lifetime; a failed fetch is not cached.
+ * @experimental
+ */
+export function fetchProofKeys(options = {}) {
+    const base = origin(options.endpoint);
+    let cached = keySets.get(base);
+    if (!cached) {
+        cached = (async () => {
+            const response = await (options.fetch ?? globalThis.fetch)(`${base}/api/public/proof/receipts/keys`, { credentials: "omit" });
+            if (!response.ok)
+                throw new Error(`Proof keys failed (${response.status}).`);
+            const data = await response.json();
+            return { keys: Array.isArray(data.keys) ? data.keys.filter((key) => Boolean(key) && typeof key === "object") : [] };
+        })();
+        cached.catch(() => keySets.delete(base));
+        keySets.set(base, cached);
+    }
+    return cached;
+}
+/** Same output as canonicalJson in lib/proof/core.ts (sorted keys, undefined dropped in objects, null in arrays). */
+function canonical(value) {
+    if (value === undefined)
+        return "null";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    return `{${Object.entries(value).filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+}
+function base64UrlBytes(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        return null;
+    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (value.length % 4)) % 4));
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+/**
+ * True only when `render.publicSignature` is a valid Ed25519 signature from a
+ * key in `keys` (matched by kid). Any failure, including a runtime without
+ * Ed25519 in WebCrypto, returns false: an unverifiable snapshot is never shown.
+ * @experimental
+ */
+export async function verifyProofRenderSignature(render, keys, subtle = globalThis.crypto?.subtle) {
+    const proof = render?.publicSignature;
+    if (!subtle || !proof || proof.alg !== "EdDSA" || typeof proof.kid !== "string" || typeof proof.signature !== "string")
+        return false;
+    const jwk = keys.keys.find((key) => key.kid === proof.kid && key.kty === "OKP" && key.crv === "Ed25519" && typeof key.x === "string");
+    const signature = base64UrlBytes(proof.signature);
+    if (!jwk || !signature)
+        return false;
+    const { signature: _hmac, publicSignature: _public, ...body } = render;
+    try {
+        const key = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+        return await subtle.verify({ name: "Ed25519" }, key, signature, new TextEncoder().encode(RENDER_SIGNATURE_PREFIX + canonical(body)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The stored static fallback to show when the live render failed, or null.
+ * Shown only when it is a render for this placement, unexpired, and carries a
+ * valid Ed25519 signature from a key the first-party JWKS publishes (previous
+ * keys stay published during a rotation). Fails closed: no keys, unknown kid,
+ * tampered payload or no Ed25519 support all yield null.
+ * @experimental
+ */
+export async function verifiedProofFallback(fallback, options = {}) {
+    const render = fallback;
+    const now = options.now ?? Date.now;
+    if (!render || typeof render !== "object" || render.schema !== "yousaid-proof-render-v1" || typeof render.expiresAt !== "string" || !isRenderFresh(render, now()))
+        return null;
+    if (options.placementId && render.placement?.id !== options.placementId)
+        return null;
+    try {
+        const keys = await fetchProofKeys({ endpoint: options.endpoint, fetch: options.fetch });
+        if (!await verifyProofRenderSignature(render, keys, options.subtle ?? globalThis.crypto?.subtle))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return isRenderFresh(render, now()) ? render : null;
+}
+/**
+ * Must match CONVERSION_NAME_PATTERN in lib/proof-publish/beacon.ts.
+ * @experimental
+ */
+export const PROOF_CONVERSION_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
+/** Live beacons on this page, so one call can report a conversion to every placement shown. */
+const activeBeacons = new Set();
+/**
+ * Reports a site conversion to every proof placement rendered on this page.
+ * Returns how many placements received it. Call it where the conversion
+ * happens on the same page (for example on the signup form's success). A page
+ * with no proof placement sends nothing.
+ * @experimental
+ */
+export function sendProofConversion(name) {
+    if (!PROOF_CONVERSION_NAME.test(name))
+        return 0;
+    let sent = 0;
+    for (const beacon of activeBeacons)
+        if (beacon.conversion(name))
+            sent += 1;
+    // <yousaid-proof> Web Components on the same page report it too (each keeps its own page-memory list).
+    if (typeof document !== "undefined") {
+        document.querySelectorAll?.("yousaid-proof").forEach((element) => { if (element.conversion?.(name))
+            sent += 1; });
+    }
+    return sent;
+}
+/**
+ * Batched, cookie-free beacon. Flushes every 5 s, at 40 queued events and when
+ * the page is hidden; a conversion flushes at once. Returns a no-op beacon when
+ * there is no event token (previews, paused placements).
+ * @experimental
+ */
+export function createProofBeacon(token, options = {}) {
+    if (!token || typeof window === "undefined")
+        return { push() { }, conversion() { return false; }, flush() { }, close() { } };
+    const url = `${origin(options.endpoint)}/api/public/proof/events`;
+    const queue = [];
+    const seen = new Set();
+    /** Items with a qualified impression in this page load. Memory only. */
+    const impressed = new Set();
+    const flush = () => {
+        if (!queue.length)
+            return;
+        // `account`: sha256 hex of the site's own account id, for CRM influence reporting. Anything else is dropped.
+        const account = options.account && /^[a-f0-9]{64}$/.test(options.account) ? options.account : undefined;
+        const body = JSON.stringify({ token, events: queue.splice(0, 50), ...(account ? { acct: account } : {}) });
+        try {
+            if (navigator.sendBeacon?.(url, new Blob([body], { type: "text/plain" })))
+                return;
+        }
+        catch { /* fall through */ }
+        void (options.fetch ?? fetch)(url, { method: "POST", body, keepalive: true, credentials: "omit", headers: { "content-type": "text/plain" } }).catch(() => undefined);
+    };
+    const timer = window.setInterval(flush, 5000);
+    const onHide = () => { if (document.visibilityState === "hidden")
+        flush(); };
+    document.addEventListener("visibilitychange", onHide);
+    const beacon = {
+        push(event, onceKey) {
+            if (onceKey) {
+                if (seen.has(onceKey))
+                    return;
+                seen.add(onceKey);
+            }
+            if (event.t === "impression")
+                impressed.add(event.i);
+            queue.push(event);
+            if (queue.length >= 40)
+                flush();
+        },
+        conversion(name) {
+            if (!PROOF_CONVERSION_NAME.test(name) || seen.has(`conv:${name}`))
+                return false;
+            seen.add(`conv:${name}`);
+            queue.push({ t: "conversion", n: name, a: [...impressed].slice(0, 50) });
+            flush();
+            return true;
+        },
+        flush,
+        close() { flush(); window.clearInterval(timer); document.removeEventListener("visibilitychange", onHide); activeBeacons.delete(beacon); },
+    };
+    activeBeacons.add(beacon);
+    return beacon;
+}
+/**
+ * YouSaid Proof collection client for the native in-app prompt. Uses the same
+ * signed end-user identity token as the rest of the SDK: identity is verified
+ * server-side and prefilled, and the customer still controls every field
+ * proposed for publication.
+ * @experimental
+ */
+export class YouSaidProofClient {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    get origin() {
+        return new URL(this.#options.endpoint ?? "https://yousaid.dev", "https://yousaid.dev").origin;
+    }
+    /** Server-side frequency caps, "not now" and "never ask" across devices. */
+    async eligibility(formId) {
+        return this.#request(`/api/proof/collect/prompt?formId=${encodeURIComponent(formId)}`);
+    }
+    /** Starts (or resumes on this device) the known customer's draft. Consumes one token nonce. */
+    async startSession(formId, presentation = "drawer") {
+        const session = await this.#request("/api/proof/collect/sessions", { method: "POST", body: JSON.stringify({ formId, presentation }) });
+        return { draftId: session.draftId, sessionToken: session.sessionToken, formId: session.formId };
+    }
+    async recordPreference(formId, action, contactPreference) {
+        await this.#request("/api/proof/collect/prompt", { method: "POST", body: JSON.stringify({ formId, action, ...(contactPreference ? { contactPreference } : {}) }) });
+    }
+    /**
+     * Resumable upload of a recording or image into the session's draft (R2
+     * multipart, up to 500 MB for video). Attach the returned `media` to an
+     * answer when you submit through your own UI.
+     */
+    async uploadMedia(session, blob, mode, options = {}) {
+        return uploadProofMedia(session.draftId, session.sessionToken, blob, mode, { ...options, endpoint: this.origin, ...(this.#options.fetch ? { fetch: this.#options.fetch } : {}) });
+    }
+    /** The hosted, embeddable page. The session secret travels in the fragment, never in a request line. */
+    frameUrl(formId, session) {
+        const base = `${this.origin}/p/${encodeURIComponent(formId)}?embed=1`;
+        return session ? `${base}#d=${encodeURIComponent(session.draftId)}.${encodeURIComponent(session.sessionToken)}` : base;
+    }
+    /** Narrows a window message to a genuine event from this origin's collection frame. */
+    parseEvent(event, frame) {
+        if (event.origin !== this.origin)
+            return null;
+        if (frame && event.source !== frame.contentWindow)
+            return null;
+        const data = event.data;
+        return data && data.source === "yousaid-proof" && typeof data.type === "string" ? data : null;
+    }
+    async #request(path, init = {}) {
+        const token = typeof this.#options.token === "function" ? await this.#options.token() : this.#options.token;
+        const request = this.#options.fetch ?? globalThis.fetch;
+        const headers = new Headers(init.headers);
+        headers.set("authorization", `Bearer ${token}`);
+        if (init.body)
+            headers.set("content-type", "application/json");
+        const response = await request(`${this.origin}${path}`, { ...init, headers, credentials: "omit" });
+        const payload = await response.json().catch(() => ({}));
+        if (!response.ok)
+            throw new Error(payload.error ?? "YouSaid could not complete the Proof request.");
+        return payload;
+    }
+}

package/dist/realtime.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Room realtime client (PRD 12.2). One WebSocket per Room with:
+ *  - catch-up by event sequence: every (re)connect sends the last processed
+ *    sequence; the server replays what was missed, or a snapshot plus the
+ *    events after it when the client is far behind;
+ *  - strict ordering: events are delivered once, in ascending sequence, even
+ *    when live events race the replay during a reconnect;
+ *  - reconnect with exponential backoff and jitter, a fresh short-lived token
+ *    per attempt, and no reconnect after the server revokes access;
+ *  - acknowledgements so the server knows the processed sequence.
+ */
+/** @experimental */
+export type RoomRealtimeEvent = {
+    id: string;
+    sequence: number;
+    type: string;
+    actorType: string;
+    actorId: string;
+    visibility: string;
+    payload: unknown;
+    createdAt: string;
+};
+/** @experimental */
+export type RoomSnapshotFrame = {
+    sequence: number;
+    events: RoomRealtimeEvent[];
+};
+/** @experimental */
+export type RealtimeStatus = "idle" | "connecting" | "catching_up" | "open" | "reconnecting" | "closed" | "revoked";
+/** @experimental */
+export type PresenceFrame = {
+    type: string;
+    principalId?: string;
+    displayName?: string;
+    members?: Array<{
+        principalId: string;
+        displayName: string;
+    }>;
+};
+type SocketLike = {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+};
+/** @experimental */
+export type SocketFactory = (url: string) => SocketLike;
+/** @experimental */
+export type RoomRealtimeOptions = {
+    roomId: string;
+    /** Mint a fresh connection: a short-lived Room token and the realtime URL (absolute or relative to `origin`). */
+    connect: () => Promise<{
+        url: string;
+        token: string;
+    }>;
+    origin?: string;
+    lastSequence?: number;
+    createSocket?: SocketFactory;
+    onEvent?: (event: RoomRealtimeEvent) => void;
+    onSnapshot?: (snapshot: RoomSnapshotFrame) => void;
+    onPresence?: (frame: PresenceFrame) => void;
+    onStatus?: (status: RealtimeStatus) => void;
+    onError?: (error: Error) => void;
+    backoff?: {
+        initialMs?: number;
+        maxMs?: number;
+    };
+    random?: () => number;
+    schedule?: (callback: () => void, ms: number) => unknown;
+    cancel?: (handle: unknown) => void;
+    /** Flush buffered replay if the server never sends `catchup.complete` (older servers). */
+    catchUpTimeoutMs?: number;
+};
+/** @experimental */
+export declare class RoomRealtimeClient {
+    #private;
+    readonly roomId: string;
+    constructor(options: RoomRealtimeOptions);
+    get lastSequence(): number;
+    get status(): RealtimeStatus;
+    start(): void;
+    stop(): void;
+    /** Typing indicators are ephemeral and never replayed. */
+    sendTyping(active: boolean): void;
+    /** Apply events fetched over HTTP (for example /events?after_seq=) through the same ordering rules. */
+    ingest(frame: {
+        snapshot?: RoomSnapshotFrame | null;
+        events: RoomRealtimeEvent[];
+    }): void;
+}
+/**
+ * Reconnect delay for attempt n (0-based): full exponential cap with 50 to 100 percent jitter.
+ * @experimental
+ */
+export declare function reconnectDelay(attempt: number, random: number, initialMs?: number, maxMs?: number): number;
+/**
+ * The partial @mention being typed at the caret, or null.
+ * @experimental
+ */
+export declare function mentionAtCaret(text: string, caret: number): {
+    query: string;
+    start: number;
+} | null;
+export {};
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"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"}

package/dist/realtime.js

@@ -0,0 +1,246 @@
+/**
+ * Room realtime client (PRD 12.2). One WebSocket per Room with:
+ *  - catch-up by event sequence: every (re)connect sends the last processed
+ *    sequence; the server replays what was missed, or a snapshot plus the
+ *    events after it when the client is far behind;
+ *  - strict ordering: events are delivered once, in ascending sequence, even
+ *    when live events race the replay during a reconnect;
+ *  - reconnect with exponential backoff and jitter, a fresh short-lived token
+ *    per attempt, and no reconnect after the server revokes access;
+ *  - acknowledgements so the server knows the processed sequence.
+ */
+const TERMINAL_CLOSE_CODES = new Set([1008, 4401, 4403]);
+/** @experimental */
+export class RoomRealtimeClient {
+    roomId;
+    #options;
+    #socket = null;
+    #lastSequence;
+    #status = "idle";
+    #attempt = 0;
+    #stopped = true;
+    #timer = null;
+    #catchUpTimer = null;
+    #buffer = [];
+    #catchingUp = false;
+    constructor(options) {
+        this.roomId = options.roomId;
+        this.#options = options;
+        this.#lastSequence = Math.max(0, options.lastSequence ?? 0);
+    }
+    get lastSequence() { return this.#lastSequence; }
+    get status() { return this.#status; }
+    start() {
+        if (!this.#stopped)
+            return;
+        this.#stopped = false;
+        void this.#open();
+    }
+    stop() {
+        this.#stopped = true;
+        this.#clearTimers();
+        const socket = this.#socket;
+        this.#socket = null;
+        if (socket) {
+            socket.onclose = null;
+            try {
+                socket.close(1000, "client stopped");
+            }
+            catch { /* already closed */ }
+        }
+        this.#setStatus("closed");
+    }
+    /** Typing indicators are ephemeral and never replayed. */
+    sendTyping(active) { this.#send({ type: active ? "typing.start" : "typing.stop" }); }
+    /** Apply events fetched over HTTP (for example /events?after_seq=) through the same ordering rules. */
+    ingest(frame) {
+        if (frame.snapshot)
+            this.#applySnapshot(frame.snapshot);
+        this.#deliver(frame.events);
+    }
+    async #open() {
+        if (this.#stopped)
+            return;
+        this.#setStatus(this.#attempt === 0 ? "connecting" : "reconnecting");
+        let target;
+        try {
+            target = await this.#options.connect();
+        }
+        catch (error) {
+            this.#options.onError?.(error instanceof Error ? error : new Error("Could not mint a Room connection."));
+            this.#scheduleReconnect();
+            return;
+        }
+        if (this.#stopped)
+            return;
+        const url = new URL(target.url, this.#options.origin ?? "https://yousaid.dev");
+        url.protocol = url.protocol === "http:" ? "ws:" : url.protocol === "https:" ? "wss:" : url.protocol;
+        url.searchParams.set("token", target.token);
+        url.searchParams.set("after_seq", String(this.#lastSequence));
+        const factory = this.#options.createSocket ?? ((address) => new WebSocket(address));
+        let socket;
+        try {
+            socket = factory(url.toString());
+        }
+        catch (error) {
+            this.#options.onError?.(error instanceof Error ? error : new Error("WebSocket unavailable."));
+            this.#scheduleReconnect();
+            return;
+        }
+        this.#socket = socket;
+        this.#catchingUp = true;
+        this.#buffer = [];
+        socket.onopen = () => { this.#attempt = 0; this.#setStatus("catching_up"); this.#armCatchUpTimeout(); };
+        socket.onmessage = (message) => this.#handle(message.data);
+        socket.onerror = () => { };
+        socket.onclose = (event) => {
+            if (this.#socket !== socket)
+                return;
+            this.#socket = null;
+            this.#flushCatchUp();
+            if (TERMINAL_CLOSE_CODES.has(event.code)) {
+                this.#stopped = true;
+                this.#setStatus("revoked");
+                return;
+            }
+            this.#scheduleReconnect();
+        };
+    }
+    #handle(data) {
+        let frame;
+        try {
+            frame = JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data));
+        }
+        catch {
+            return;
+        }
+        const type = String(frame.type ?? "");
+        if (type === "room.event" && frame.event) {
+            const event = frame.event;
+            if (this.#catchingUp)
+                this.#buffer.push(event);
+            else
+                this.#deliver([event]);
+            return;
+        }
+        if (type === "room.snapshot" && frame.snapshot) {
+            this.#applySnapshot(frame.snapshot);
+            return;
+        }
+        if (type === "catchup.complete") {
+            this.#flushCatchUp();
+            this.#setStatus("open");
+            return;
+        }
+        if (type === "access.revoked") {
+            this.#stopped = true;
+            this.#setStatus("revoked");
+            return;
+        }
+        if (type === "connected" || type === "pong" || type === "error")
+            return;
+        this.#options.onPresence?.(frame);
+    }
+    #applySnapshot(snapshot) {
+        if (snapshot.sequence <= this.#lastSequence)
+            return;
+        // Buffered events at or below the snapshot are already folded into it.
+        this.#buffer = this.#buffer.filter((event) => event.sequence > snapshot.sequence);
+        this.#lastSequence = snapshot.sequence;
+        this.#options.onSnapshot?.({ sequence: snapshot.sequence, events: [...snapshot.events].sort((left, right) => left.sequence - right.sequence) });
+        this.#ack();
+    }
+    #flushCatchUp() {
+        if (this.#catchUpTimer !== null) {
+            (this.#options.cancel ?? clearTimeout)(this.#catchUpTimer);
+            this.#catchUpTimer = null;
+        }
+        if (!this.#catchingUp)
+            return;
+        this.#catchingUp = false;
+        const buffered = this.#buffer;
+        this.#buffer = [];
+        this.#deliver(buffered);
+    }
+    /** Deliver in ascending sequence, dropping anything already processed. */
+    #deliver(events) {
+        const ordered = [...events].filter((event) => Number.isInteger(event.sequence)).sort((left, right) => left.sequence - right.sequence);
+        let delivered = false;
+        for (const event of ordered) {
+            if (event.sequence <= this.#lastSequence)
+                continue;
+            this.#lastSequence = event.sequence;
+            delivered = true;
+            try {
+                this.#options.onEvent?.(event);
+            }
+            catch (error) {
+                this.#options.onError?.(error instanceof Error ? error : new Error("Room event handler failed."));
+            }
+        }
+        if (delivered)
+            this.#ack();
+    }
+    #ack() { this.#send({ type: "ack", sequence: this.#lastSequence }); }
+    #send(payload) {
+        const socket = this.#socket;
+        if (!socket || socket.readyState !== 1)
+            return;
+        try {
+            socket.send(JSON.stringify(payload));
+        }
+        catch { /* the close handler reconnects */ }
+    }
+    #armCatchUpTimeout() {
+        const schedule = this.#options.schedule ?? ((callback, ms) => setTimeout(callback, ms));
+        this.#catchUpTimer = schedule(() => { this.#catchUpTimer = null; this.#flushCatchUp(); if (this.#socket)
+            this.#setStatus("open"); }, this.#options.catchUpTimeoutMs ?? 3_000);
+    }
+    #scheduleReconnect() {
+        if (this.#stopped)
+            return;
+        this.#setStatus("reconnecting");
+        const initial = this.#options.backoff?.initialMs ?? 500;
+        const maximum = this.#options.backoff?.maxMs ?? 30_000;
+        const delay = reconnectDelay(this.#attempt, (this.#options.random ?? Math.random)(), initial, maximum);
+        this.#attempt += 1;
+        const schedule = this.#options.schedule ?? ((callback, ms) => setTimeout(callback, ms));
+        this.#timer = schedule(() => { this.#timer = null; void this.#open(); }, delay);
+    }
+    #clearTimers() {
+        const cancel = this.#options.cancel ?? ((handle) => clearTimeout(handle));
+        if (this.#timer !== null) {
+            cancel(this.#timer);
+            this.#timer = null;
+        }
+        if (this.#catchUpTimer !== null) {
+            cancel(this.#catchUpTimer);
+            this.#catchUpTimer = null;
+        }
+    }
+    #setStatus(status) {
+        if (this.#status === status)
+            return;
+        this.#status = status;
+        this.#options.onStatus?.(status);
+    }
+}
+/**
+ * Reconnect delay for attempt n (0-based): full exponential cap with 50 to 100 percent jitter.
+ * @experimental
+ */
+export function reconnectDelay(attempt, random, initialMs = 500, maxMs = 30_000) {
+    const exponential = Math.min(maxMs, initialMs * 2 ** attempt);
+    return Math.round(exponential / 2 + random * exponential / 2);
+}
+/**
+ * The partial @mention being typed at the caret, or null.
+ * @experimental
+ */
+export function mentionAtCaret(text, caret) {
+    const before = text.slice(0, Math.max(0, caret));
+    const match = before.match(/(^|\s)@([a-z]{0,20})$/i);
+    if (!match)
+        return null;
+    return { query: (match[2] ?? "").toLowerCase(), start: before.length - (match[2] ?? "").length - 1 };
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@sansavision/yousaid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Framework-free YouSaid client: signals, inbox, release receipts and diagnostics.",
+  "private": false,
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sansa-Organisation/yousaid.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://yousaid.dev/docs/sdk",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}