@doany-ai/inbox 0.0.0-stage → 0.1.0

package/dist/session.js

@@ -0,0 +1,613 @@
+import { READ_KEY } from "./storage.js";
+/** While an answer is on its way. */
+export const POLL_REPLY_MS = 2000;
+/** With the panel open. */
+export const POLL_OPEN_MS = 5000;
+/** With the panel closed, on a page with a chat. */
+export const POLL_CLOSED_MS = 30000;
+/** Polling stops after this long with nothing happening, and restarts on tab focus or panel open. */
+export const IDLE_MS = 30 * 60 * 1000;
+/** The longest wait between reads after failures. */
+export const MAX_BACKOFF_MS = 60000;
+/** A booking still waiting for its payment is reported again no sooner than this after the last time. */
+export const BOOKING_REPORT_MS = 15000;
+/** A booking still waiting for its payment after this long is no longer reported. */
+export const BOOKING_REPORT_FOR_MS = 60 * 60 * 1000;
+/** What one read returns at most (the platform's page). */
+const THREAD_PAGE = 100;
+/** Pages read in one poll before waiting for the next. */
+const MAX_PAGES = 10;
+const INITIAL = {
+    ready: false,
+    hasChat: false,
+    email: null,
+    me: null,
+    messages: [],
+    replyPending: false,
+    paused: false,
+    off: false,
+    closed: false,
+    pending: null,
+    draft: null,
+    busy: false,
+    problem: null,
+    retryAfter: null,
+    linkExpired: false,
+    unread: false,
+};
+/** What a refusal means here. The SDK's error keeps the status, the code and the response body (`data`). */
+export function refusalOf(error) {
+    const { status, code, data } = (error ?? {});
+    const details = data?.details ?? {};
+    const reason = details.reason;
+    const retryAfter = typeof details.retry_after === "number" ? details.retry_after : null;
+    const refusal = (problem, notFound = false) => ({ status, notFound, problem, retryAfter });
+    if (code === "INBOX_NOT_FOUND")
+        return refusal("failed", true);
+    if (code === "INBOX_OFF")
+        return refusal("off");
+    if (reason === "blocked")
+        return refusal("closed");
+    if (reason === "preview_only")
+        return refusal("not_published");
+    if (status === 429)
+        return refusal(reason === "contact_limit" ? "contact_limit" : reason === "chat_limit" ? "chat_limit" : "rate_limited");
+    if (status === 400 && details.errors?.some((e) => e.field === "contact" && e.code === "required"))
+        return refusal("details_required");
+    return refusal("failed");
+}
+/**
+ * One browser's chat with the business: the thread and its polling, over the
+ * SDK's `client.inbox`, which holds the token and a first message still owed.
+ * No DOM: the default widget and a site's own chat UI drive it the same way.
+ * `useInbox()` wraps it for React.
+ */
+export class InboxSession {
+    constructor(client, storage) {
+        this.client = client;
+        this.storage = storage;
+        this.state = INITIAL;
+        this.listeners = new Set();
+        this.options = { active: true, open: false, visible: true };
+        this.actor = null;
+        this.chat = false;
+        this.cursor = null;
+        this.serverMessages = [];
+        this.localMessages = [];
+        this.lastSend = null;
+        this.timer = null;
+        this.inFlight = false;
+        this.failures = 0;
+        this.waitSeconds = null;
+        this.lastActivity = Date.now();
+        this.stopped = false;
+        /** Bumped whenever the chat changes hands, so a late answer for the old one is dropped. */
+        this.generation = 0;
+        this.attached = false;
+        this.seenFor = null;
+        /** Bookings already reported, by registration id. */
+        this.reported = new Set();
+        /**
+         * Bookings reported while waiting for their payment, oldest first. The
+         * platform notes a booking only once it is confirmed, so each is reported
+         * again alongside the reads until its line is in the thread.
+         */
+        this.unpaid = [];
+        this.resolveReady = () => { };
+        this.whenReady = new Promise((resolve) => {
+            this.resolveReady = resolve;
+        });
+        /** Called after each read, so the page can re-read the button's settings alongside it. */
+        this.onPoll = null;
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => {
+                this.listeners.delete(listener);
+            };
+        };
+        this.getState = () => this.state;
+        /** The first message of a chat. Resolves true once the platform has it. */
+        this.start = async (input) => {
+            await this.whenReady;
+            const text = input.text.trim();
+            if (!text || this.chat || this.state.pending || this.state.busy)
+                return false;
+            const { pagePath, language, capabilities } = this.options;
+            const contact = input.contact ? cleanContact(input.contact) : undefined;
+            const intent = input.intent ?? "ask";
+            this.set({ draft: null, linkExpired: false, closed: false });
+            this.showPending("sending", { text, intent, contact });
+            return this.sendPending(() => this.client.inbox.start({
+                text,
+                intent,
+                ...(contact ? { contact } : {}),
+                ...(pagePath ? { pagePath: pagePath.slice(0, 2000) } : {}),
+                ...(language ? { language: language.slice(0, 100) } : {}),
+                ...(capabilities?.length ? { capabilities } : {}),
+            }), { text, intent, contact: contact ?? null });
+        };
+        /** Sends the first message that was not confirmed again, unchanged. */
+        this.retryPending = async () => {
+            if (!this.state.pending || this.state.busy)
+                return false;
+            this.showPending("sending");
+            return this.sendPending(() => this.client.inbox.start());
+        };
+        /** A later message in the chat. Resolves true once the platform has it; on false the page keeps the words. */
+        this.send = async (input) => {
+            const text = input.trim();
+            if (!this.chat || !text || this.state.busy)
+                return false;
+            // The same words again after a failure keep their id: a lost answer is not stored twice.
+            const id = this.lastSend?.text === text ? this.lastSend.id : this.client.inbox.newMessageId();
+            this.lastSend = { text, id };
+            const generation = this.generation;
+            const { capabilities } = this.options;
+            this.set({ busy: true, problem: null, retryAfter: null });
+            try {
+                const receipt = await this.client.inbox.send({ text, clientMessageId: id, ...(capabilities?.length ? { capabilities } : {}) });
+                if (generation !== this.generation)
+                    return false;
+                this.lastSend = null;
+                this.localMessages.push(receipt.message);
+                this.set({ busy: false, replyPending: receipt.reply_pending, off: false, messages: this.thread() });
+                this.touch();
+                // Soon, for the lines that follow it ("Sent to the team.").
+                this.schedule(receipt.reply_pending ? undefined : POLL_REPLY_MS);
+                return true;
+            }
+            catch (error) {
+                if (generation !== this.generation)
+                    return false;
+                this.refused(error);
+                return false;
+            }
+        };
+        /** Hands the chat to a person, with the words in the box if any. */
+        this.askForPerson = async (input) => {
+            const text = input?.trim();
+            if (!this.chat || this.state.busy)
+                return false;
+            const generation = this.generation;
+            this.set({ busy: true, problem: null, retryAfter: null });
+            try {
+                await this.client.inbox.person(text ? { text } : undefined);
+                if (generation !== this.generation)
+                    return false;
+                this.set({ busy: false, off: false });
+                this.touch();
+                this.schedule(0);
+                return true;
+            }
+            catch (error) {
+                if (generation !== this.generation)
+                    return false;
+                this.refused(error);
+                return false;
+            }
+        };
+        /**
+         * Opens the token of a reply's emailed link: the chat moves to this browser.
+         * A link that no longer works leaves this browser's own chat as it was and
+         * sets `linkExpired`.
+         */
+        this.resume = async (linkToken) => {
+            await this.whenReady;
+            const generation = this.generation;
+            this.set({ busy: true, linkExpired: false, problem: null });
+            try {
+                const { me } = await this.client.inbox.resume(linkToken);
+                if (generation !== this.generation)
+                    return false;
+                this.load();
+                this.set({ me });
+                return true;
+            }
+            catch (error) {
+                if (generation !== this.generation)
+                    return false;
+                const refusal = refusalOf(error);
+                if (refusal.notFound || refusal.status === 400) {
+                    this.set({ busy: false, linkExpired: true });
+                }
+                else {
+                    this.set({ busy: false, problem: refusal.problem, retryAfter: refusal.retryAfter, closed: refusal.problem === "closed" });
+                }
+                return false;
+            }
+        };
+        /**
+         * A booking the site's flow made from an offer in this chat (the flow's
+         * `onBooked`). The platform notes it on the chat, and the business's Inbox
+         * and Calendar link the two, when the booking is this chat's and confirmed.
+         * Each booking is reported once; one still waiting for its payment
+         * (`registration.status` `pending_payment`) is not booked yet, so it is
+         * reported again alongside the reads, for up to an hour, until the thread
+         * shows its line. Resolves false when there was nothing to report or the
+         * report did not go through; the booking stands either way.
+         */
+        this.reportBooking = async (result) => {
+            const registrationId = result.registration?.id;
+            const accessToken = result.access_token;
+            if (!this.chat || !registrationId || !accessToken || this.reported.has(registrationId))
+                return false;
+            this.reported.add(registrationId);
+            if (result.registration?.status === "pending_payment") {
+                const now = Date.now();
+                this.unpaid.push({ registrationId, accessToken, since: now, last: now });
+            }
+            const generation = this.generation;
+            try {
+                await this.client.inbox.bookings({ registrationId, accessToken });
+            }
+            catch (error) {
+                if (generation === this.generation && refusalOf(error).notFound)
+                    this.load();
+                return false;
+            }
+            if (generation !== this.generation)
+                return false;
+            // Read at once: the note follows the booking in the thread.
+            this.touch();
+            this.schedule(0);
+            return true;
+        };
+        /** Forgets this browser's chat with no call: the next message starts a new one. */
+        this.newChat = () => {
+            this.client.inbox.forget();
+            this.reset();
+        };
+        /** Something happened (the tab came back, the panel opened): polling restarts if it had stopped. */
+        this.wake = (now = false) => {
+            this.touch();
+            if (!this.chat || !this.attached || this.state.closed || !this.options.active)
+                return;
+            if (now || this.stopped || (!this.timer && !this.inFlight))
+                this.schedule(0);
+        };
+        /** The panel shows the newest reply: clear the button's mark. */
+        this.markRead = () => {
+            const newest = this.newestTeamMessage();
+            if (newest)
+                this.storage.set(READ_KEY, newest.id);
+            if (this.state.unread)
+                this.set({ unread: false });
+        };
+    }
+    set(patch) {
+        this.state = { ...this.state, ...patch };
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** Starts polling (when there is a chat). A detached session keeps its state and makes no calls. */
+    attach() {
+        this.attached = true;
+        if (this.chat)
+            this.schedule(0);
+    }
+    detach() {
+        this.attached = false;
+        this.clearTimer();
+    }
+    setOptions(options) {
+        const opening = options.open === true && !this.options.open;
+        const closing = options.open === false && this.options.open;
+        const showing = options.visible === true && !this.options.visible;
+        const activating = options.active === true && !this.options.active;
+        const deactivating = options.active === false && this.options.active;
+        this.options = { ...this.options, ...options };
+        if (deactivating) {
+            this.clearTimer();
+            return;
+        }
+        if (activating && !opening) {
+            this.wake(true);
+            return;
+        }
+        if (opening) {
+            this.markRead();
+            this.wake(true);
+        }
+        else if (closing) {
+            // The panel closed: read at the slower pace from now on.
+            if (this.timer)
+                this.schedule();
+        }
+        else if (showing) {
+            this.maybeSeen();
+        }
+    }
+    /**
+     * Who is using the site: `guest`, or `user:<id>` for a signed-in account.
+     * The SDK keeps a chat per account, so a change reads the chat again.
+     */
+    setActor(actor) {
+        if (actor === this.actor)
+            return;
+        this.actor = actor;
+        this.load();
+        this.resolveReady();
+    }
+    /** Reads which chat this browser holds, from the SDK, and starts from there. */
+    load() {
+        this.reset();
+        const held = this.client.inbox.current();
+        if (held) {
+            this.chat = true;
+            this.set({ ready: true, hasChat: true, email: held.email });
+            this.touch();
+            if (this.attached)
+                this.schedule(0);
+            return;
+        }
+        this.set({ ready: true });
+        if (this.client.inbox.pendingStart()) {
+            // A reload during the first send: send it once more, unchanged, before asking again.
+            this.showPending("sending");
+            void this.sendPending(() => this.client.inbox.start());
+        }
+    }
+    reset() {
+        this.generation += 1;
+        this.clearTimer();
+        this.chat = false;
+        this.cursor = null;
+        this.serverMessages = [];
+        this.localMessages = [];
+        this.lastSend = null;
+        this.failures = 0;
+        this.waitSeconds = null;
+        this.stopped = false;
+        this.seenFor = null;
+        this.unpaid = [];
+        this.set({ ...INITIAL, ready: this.state.ready });
+    }
+    showPending(state, given) {
+        const pending = given ?? this.client.inbox.pendingStart();
+        if (!pending)
+            return;
+        this.set({ pending: { text: pending.text, intent: pending.intent, email: pending.contact?.email ?? null, state } });
+    }
+    async sendPending(call, given) {
+        const generation = this.generation;
+        const asked = given ?? this.client.inbox.pendingStart();
+        this.set({ busy: true, problem: null, retryAfter: null });
+        try {
+            const receipt = await call();
+            if (generation !== this.generation)
+                return false;
+            const held = this.client.inbox.current();
+            this.chat = true;
+            this.localMessages = [receipt.message];
+            this.set({
+                hasChat: true,
+                email: receipt.me.signed_in ? null : held?.email ?? asked?.contact?.email ?? null,
+                me: receipt.me,
+                pending: null,
+                busy: false,
+                replyPending: receipt.reply_pending,
+                off: false,
+                messages: this.thread(),
+            });
+            this.touch();
+            this.schedule();
+            return true;
+        }
+        catch (error) {
+            if (generation !== this.generation)
+                return false;
+            const refusal = refusalOf(error);
+            const closed = refusal.problem === "closed";
+            // The SDK keeps the first message while its answer is owed (a lost
+            // answer, a limit, the button off) and resends it unchanged: locked.
+            if (this.client.inbox.pendingStart()) {
+                this.set({ busy: false, problem: refusal.problem, retryAfter: refusal.retryAfter, closed });
+                this.showPending("failed");
+                return false;
+            }
+            // Refused for good: nothing was made. The words go back in the box.
+            this.set({
+                busy: false,
+                pending: null,
+                draft: asked ? { text: asked.text, intent: asked.intent, contact: asked.contact ?? null } : null,
+                problem: refusal.problem,
+                retryAfter: refusal.retryAfter,
+                closed,
+            });
+            return false;
+        }
+    }
+    /** Reports the bookings still waiting for their payment again. A report that fails waits for the next read. */
+    async reportUnpaid() {
+        const now = Date.now();
+        this.unpaid = this.unpaid.filter((booking) => now - booking.since < BOOKING_REPORT_FOR_MS);
+        for (const booking of this.unpaid) {
+            if (now - booking.last < BOOKING_REPORT_MS)
+                continue;
+            booking.last = now;
+            try {
+                await this.client.inbox.bookings({ registrationId: booking.registrationId, accessToken: booking.accessToken });
+            }
+            catch {
+                // The read that follows says what happened to the chat.
+            }
+        }
+    }
+    touch() {
+        this.lastActivity = Date.now();
+        this.stopped = false;
+    }
+    clearTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    /** The next read: 2 s while an answer is on its way, 5 s with the panel open, 30 s closed; longer after failures; none after 30 idle minutes. */
+    schedule(delay) {
+        this.clearTimer();
+        if (!this.attached || !this.chat || this.state.closed || !this.options.active)
+            return;
+        if (delay !== 0 && Date.now() - this.lastActivity >= IDLE_MS) {
+            this.stopped = true;
+            return;
+        }
+        const base = this.state.replyPending ? POLL_REPLY_MS : this.options.open ? POLL_OPEN_MS : POLL_CLOSED_MS;
+        let wait = delay ?? base;
+        if (this.failures && delay === undefined) {
+            wait = Math.max(Math.min(base * 2 ** this.failures, MAX_BACKOFF_MS), (this.waitSeconds ?? 0) * 1000);
+        }
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.poll();
+        }, wait);
+    }
+    async poll() {
+        if (!this.chat || this.inFlight || !this.attached)
+            return;
+        const generation = this.generation;
+        this.inFlight = true;
+        try {
+            let page;
+            let pages = 0;
+            let fresh = [];
+            let restarted = false;
+            if (this.unpaid.length) {
+                // Before the read, so a booking paid since shows its line in this one.
+                await this.reportUnpaid();
+                if (generation !== this.generation)
+                    return;
+            }
+            do {
+                page = await this.client.inbox.messages(this.cursor ? { cursor: this.cursor } : {});
+                if (generation !== this.generation)
+                    return;
+                // The cursor could not be used: the SDK read from the start.
+                if (page.restarted) {
+                    this.serverMessages = [];
+                    restarted = true;
+                }
+                fresh = fresh.concat(this.merge(page.messages));
+                if (page.next_cursor)
+                    this.cursor = page.next_cursor;
+                pages += 1;
+            } while (page.messages.length >= THREAD_PAGE && pages < MAX_PAGES);
+            this.failures = 0;
+            this.waitSeconds = null;
+            // Each new "You're booked" line settles the oldest booking still waiting
+            // (a thread read again from the start brings back old lines, not new ones).
+            if (!restarted) {
+                const booked = fresh.filter((row) => row.kind === "event" && row.payload?.code === "booking_made").length;
+                if (booked)
+                    this.unpaid = this.unpaid.slice(booked);
+            }
+            this.apply(page, fresh);
+        }
+        catch (error) {
+            if (generation !== this.generation)
+                return;
+            const refusal = refusalOf(error);
+            if (refusal.notFound) {
+                // The SDK forgot that token: whatever it holds now (usually nothing) is the chat.
+                this.load();
+                return;
+            }
+            if (refusal.problem === "closed") {
+                this.set({ closed: true, problem: "closed" });
+                return;
+            }
+            this.failures += 1;
+            this.waitSeconds = refusal.retryAfter;
+        }
+        finally {
+            this.inFlight = false;
+            if (generation === this.generation) {
+                this.onPoll?.();
+                this.schedule();
+            }
+        }
+    }
+    /** The platform's rows in its order, each once; returns the ones not seen before. */
+    merge(rows) {
+        const known = new Set(this.serverMessages.map((message) => message.id));
+        const fresh = rows.filter((row) => !known.has(row.id));
+        this.serverMessages = this.serverMessages.concat(fresh);
+        return fresh;
+    }
+    thread() {
+        const shown = new Set(this.serverMessages.map((message) => message.id));
+        this.localMessages = this.localMessages.filter((message) => !shown.has(message.id));
+        return this.serverMessages.concat(this.localMessages);
+    }
+    newestTeamMessage() {
+        for (let i = this.serverMessages.length - 1; i >= 0; i--) {
+            if (this.serverMessages[i].author === "team")
+                return this.serverMessages[i];
+        }
+        return null;
+    }
+    apply(page, fresh) {
+        if (fresh.length)
+            this.touch();
+        const newest = this.newestTeamMessage();
+        let unread = false;
+        if (newest) {
+            if (this.options.open)
+                this.storage.set(READ_KEY, newest.id);
+            else
+                unread = this.storage.get(READ_KEY) !== newest.id;
+        }
+        this.set({
+            messages: this.thread(),
+            replyPending: page.reply_pending,
+            paused: page.paused,
+            off: page.off,
+            me: page.me,
+            email: page.me.signed_in ? null : this.client.inbox.current()?.email ?? this.state.email,
+            unread,
+            problem: this.state.problem === "off" && !page.off ? null : this.state.problem,
+        });
+        this.maybeSeen();
+    }
+    /** Tells the platform the newest team reply was shown: only with the panel open and the page visible. */
+    maybeSeen() {
+        const cursor = this.cursor;
+        if (!this.chat || !cursor || !this.options.open || !this.options.visible)
+            return;
+        const newest = this.newestTeamMessage();
+        if (!newest || this.seenFor === newest.id)
+            return;
+        const previous = this.seenFor;
+        this.seenFor = newest.id;
+        this.client.inbox.seen(cursor).catch(() => {
+            if (this.seenFor === newest.id)
+                this.seenFor = previous;
+        });
+    }
+    refused(error) {
+        const refusal = refusalOf(error);
+        if (refusal.notFound) {
+            // The SDK forgot that token: start from what it holds now.
+            this.load();
+            return;
+        }
+        this.set({
+            busy: false,
+            problem: refusal.problem,
+            retryAfter: refusal.retryAfter,
+            off: refusal.problem === "off" || this.state.off,
+            closed: refusal.problem === "closed",
+        });
+        if (refusal.problem === "closed")
+            this.clearTimer();
+    }
+    /** Stops every timer. The session can be attached again. */
+    dispose() {
+        this.detach();
+        this.listeners.clear();
+    }
+}
+function cleanContact(contact) {
+    const name = contact.name?.trim();
+    const phone = contact.phone?.trim();
+    return { email: contact.email.trim(), ...(name ? { name: name.slice(0, 80) } : {}), ...(phone ? { phone } : {}) };
+}

package/dist/storage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What this package keeps itself: only which team reply was last shown with
+ * the panel open, so a reload does not mark it unread again. The chat's token
+ * and a first message still owed are the SDK's (`client.inbox`), kept per
+ * account. A site can pass its own storage. No method throws.
+ */
+export interface InboxStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+export declare function memoryStorage(): InboxStorage;
+/** The browser's localStorage when it can be used, else memory for this page. */
+export declare function defaultStorage(): InboxStorage;
+/** The visitor hid the privacy line: kept for the browser session. */
+export declare const PRIVACY_DISMISSED_KEY = "doany_inbox_privacy_dismissed";
+/** A mark kept for the browser session; for this page only where the session's storage cannot be used. */
+export declare function sessionMark(key: string): boolean;
+export declare function setSessionMark(key: string): void;
+/** The newest team message shown with the panel open. Message ids are unique, so one key serves every chat. */
+export declare const READ_KEY = "doany_inbox_read";