@pocketboss/core 0.1.0 → 0.2.0

package/README.md

@@ -39,3 +39,29 @@ The bridge methods `client.pickFiles()` and `client.capturePhoto()` remain separ
 The client validates v1 messages and method payloads against generated copies of `packages/bridge-contract/schemas`, enforces message and pending-request limits, correlates random UUID requests, checks launch binding and event sequence, and cancels work on abort, timeout, pause and teardown. Native still owns sender verification, permission checks, and launch-ticket exchange.
 
 Run `npm run build:core` and `npm test -w @pocketboss/core` from the repository root. Regenerate contract types before every build.
+
+## Business order comments
+
+The core comments client/custom element works in vanilla JS and is the shared implementation used by every framework wrapper. Give it the PocketBoss order ULID, a workspace key, and session callbacks that call your same-origin Mini App backend. The backend owns business authorization and integration credentials; the browser receives only a short-lived, scoped comments token.
+
+```ts
+import { registerOrderCommentsElement } from '@pocketboss/core/comments';
+import type { OrderCommentMessage, PocketBossOrderCommentsElement } from '@pocketboss/core/comments';
+
+registerOrderCommentsElement();
+const element = document.querySelector('pb-order-comments') as PocketBossOrderCommentsElement;
+element.options = {
+  apiBaseUrl: 'https://api.example.test/api/v1',
+  orderId: pocketBossOrderId,
+  workspaceKey: businessId,
+  sessions, // create/revoke via same-origin /api/business/order-comments/session
+  placement: 'inline', // modal, bottom-sheet, full-page, or headless also work
+  renderMessage(message: OrderCommentMessage) {
+    const bubble = document.createElement('article');
+    bubble.textContent = message.text; // user-authored text: do not use innerHTML
+    return bubble;
+  },
+};
+```
+
+See the [end-to-end SDK guide](../../docs/SDK_GUIDE.md#registration-to-comments-fixture) and [sample backend](../../examples/sample-mini-app-backend/README.md) for access modes, registration, server-side customer assertion verification, order sync, and session lifecycle. `renderMessage` is optional; omitting it uses the default accessible renderer.

package/dist/comments/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../comments.js';
+export * from '../comments-element.js';

package/dist/comments/index.js

@@ -0,0 +1,2 @@
+export * from '../comments.js';
+export * from '../comments-element.js';

package/dist/comments-element.d.ts

@@ -0,0 +1,37 @@
+import { OrderCommentsClient } from './comments.js';
+import type { OrderCommentMessage, OrderCommentsClientOptions } from './comments.js';
+export type OrderCommentsPlacement = 'inline' | 'modal' | 'bottom-sheet' | 'full-page' | 'headless';
+export type OrderCommentsThemeMode = 'light' | 'dark' | 'auto';
+export interface OrderCommentsTheme {
+    mode?: OrderCommentsThemeMode;
+    accent?: string;
+    surface?: string;
+    text?: string;
+    muted?: string;
+    border?: string;
+    customerBubble?: string;
+    customerText?: string;
+    businessBubble?: string;
+    businessText?: string;
+    fontFamily?: string;
+    spacing?: number;
+    radius?: number;
+}
+export interface OrderCommentsElementOptions extends OrderCommentsClientOptions {
+    workspaceKey: string;
+    placement?: OrderCommentsPlacement;
+    theme?: OrderCommentsTheme;
+    title?: string;
+    language?: string;
+    /** Return a DOM node for a message. Use textContent for untrusted message text. */
+    renderMessage?: (message: OrderCommentMessage) => HTMLElement;
+}
+export interface PocketBossOrderCommentsElement extends HTMLElement {
+    options: OrderCommentsElementOptions;
+    readonly commentsClient: OrderCommentsClient | null;
+    loadComments(): Promise<void>;
+    openCommentsClient(): Promise<OrderCommentsClient>;
+}
+/** Register the framework-neutral comments element. Safe to call during SSR. */
+export declare function registerOrderCommentsElement(tagName?: string): void;
+export declare function mountOrderCommentsElement(element: HTMLElement, options: OrderCommentsElementOptions): PocketBossOrderCommentsElement;

package/dist/comments-element.js

@@ -0,0 +1,468 @@
+import { OrderCommentsClient, OrderCommentsError, } from './comments.js';
+const defaultTagName = 'pb-order-comments';
+let commentsCloseBarrier = Promise.resolve();
+/** Register the framework-neutral comments element. Safe to call during SSR. */
+export function registerOrderCommentsElement(tagName = defaultTagName) {
+    if (typeof window === 'undefined' || !('customElements' in window))
+        return;
+    if (customElements.get(tagName))
+        return;
+    class PocketBossOrderComments extends HTMLElement {
+        root;
+        currentOptions = null;
+        currentClient = null;
+        pendingClose = Promise.resolve();
+        messages = [];
+        nextCursor = null;
+        unreadCount = 0;
+        loading = false;
+        sending = false;
+        error = null;
+        expired = false;
+        opened = false;
+        draft = '';
+        pendingText = null;
+        pendingId = null;
+        loadSequence = 0;
+        lastReadMessageId = null;
+        constructor() {
+            super();
+            this.root = this.attachShadow({ mode: 'open' });
+        }
+        get options() {
+            if (!this.currentOptions)
+                throw new Error('Order comments options have not been set.');
+            return this.currentOptions;
+        }
+        set options(value) {
+            const old = this.currentOptions;
+            this.currentOptions = value;
+            if (old && contextKey(old) !== contextKey(value)) {
+                this.closeCurrentClient();
+                this.resetConversation();
+            }
+            this.applyTheme(value.theme ?? {});
+            this.render();
+            if (this.isConnected && isInitiallyOpen(value.placement) && !old)
+                void this.load();
+            if (this.isConnected && isInitiallyOpen(value.placement) && old && contextKey(old) !== contextKey(value))
+                void this.load();
+        }
+        get commentsClient() {
+            return this.currentClient;
+        }
+        async loadComments() {
+            if (this.currentOptions?.placement === 'headless') {
+                await this.ensureClient();
+                return;
+            }
+            if (this.currentOptions?.placement === 'modal' || this.currentOptions?.placement === 'bottom-sheet')
+                return;
+            await this.load();
+        }
+        openCommentsClient() {
+            return this.ensureClient();
+        }
+        connectedCallback() {
+            this.render();
+            if (this.currentOptions && isInitiallyOpen(this.currentOptions.placement))
+                void this.load();
+        }
+        disconnectedCallback() {
+            this.closeCurrentClient();
+        }
+        async ensureClient() {
+            await commentsCloseBarrier;
+            await this.pendingClose;
+            if (!this.currentOptions)
+                throw new OrderCommentsError('Order comments options have not been set.');
+            if (!this.currentClient || !this.currentClient.active) {
+                this.currentClient = new OrderCommentsClient(this.currentOptions);
+            }
+            return this.currentClient;
+        }
+        closeCurrentClient() {
+            const client = this.currentClient;
+            this.currentClient = null;
+            if (client) {
+                this.pendingClose = client.close();
+                commentsCloseBarrier = Promise.all([commentsCloseBarrier, this.pendingClose]).then(() => undefined);
+                void commentsCloseBarrier.catch(() => { });
+            }
+        }
+        resetConversation() {
+            this.messages = [];
+            this.nextCursor = null;
+            this.unreadCount = 0;
+            this.loading = false;
+            this.error = null;
+            this.expired = false;
+            this.pendingId = null;
+            this.pendingText = null;
+            this.lastReadMessageId = null;
+            this.loadSequence++;
+        }
+        async load(cursor) {
+            if (!this.currentOptions || this.loading)
+                return;
+            const sequence = ++this.loadSequence;
+            this.loading = true;
+            this.error = null;
+            this.expired = false;
+            this.render();
+            try {
+                const page = await (await this.ensureClient()).messages(cursor);
+                if (sequence !== this.loadSequence || !this.isConnected)
+                    return;
+                const old = new Set(this.messages.map((message) => message.messageId));
+                this.messages = cursor
+                    ? [...this.messages, ...page.messages.filter((message) => !old.has(message.messageId))]
+                    : page.messages;
+                this.nextCursor = page.nextCursor;
+                this.unreadCount = page.unreadCount;
+                this.markLatestBusinessMessageRead();
+            }
+            catch (error) {
+                if (sequence !== this.loadSequence)
+                    return;
+                this.showError(error);
+            }
+            finally {
+                if (sequence === this.loadSequence) {
+                    this.loading = false;
+                    this.render();
+                }
+            }
+        }
+        async send() {
+            const text = this.draft.trim();
+            if (!text || text.length > 5000 || this.sending)
+                return;
+            if (this.pendingText !== text || !this.pendingId) {
+                this.pendingText = text;
+                this.pendingId = secureUuid();
+            }
+            this.sending = true;
+            this.error = null;
+            this.render();
+            try {
+                const message = await (await this.ensureClient()).send(text, this.pendingId);
+                if (!this.isConnected)
+                    return;
+                if (!this.messages.some((existing) => existing.messageId === message.messageId))
+                    this.messages.push(message);
+                this.draft = '';
+                this.pendingId = null;
+                this.pendingText = null;
+                this.unreadCount = 0;
+            }
+            catch (error) {
+                this.showError(error);
+            }
+            finally {
+                this.sending = false;
+                this.render();
+            }
+        }
+        markLatestBusinessMessageRead() {
+            const last = [...this.messages].reverse().find((message) => message.participantSide === 'business');
+            if (!last || last.messageId === this.lastReadMessageId || !this.currentClient)
+                return;
+            this.lastReadMessageId = last.messageId;
+            void this.currentClient.markRead(last.messageId).catch(() => {
+                if (this.lastReadMessageId === last.messageId)
+                    this.lastReadMessageId = null;
+            });
+        }
+        showError(value) {
+            const error = value instanceof OrderCommentsError ? value : null;
+            this.expired = error?.status === 401 || error?.status === 410 || error?.code === 'COMMENTS_SESSION_EXPIRED';
+            this.error = this.expired
+                ? 'Comments access expired. Reconnect to renew this secure session.'
+                : error?.status === 403 || error?.status === 404
+                    ? 'This order is not available to the current business workspace.'
+                    : error?.message ?? 'Order comments are unavailable. Retry in a moment.';
+        }
+        applyTheme(theme) {
+            const colors = [
+                ['accent', theme.accent],
+                ['surface', theme.surface],
+                ['text', theme.text],
+                ['muted', theme.muted],
+                ['border', theme.border],
+                ['customer', theme.customerBubble],
+                ['customer-text', theme.customerText],
+                ['business', theme.businessBubble],
+                ['business-text', theme.businessText],
+            ];
+            for (const [name, value] of colors) {
+                const safe = safeColor(value);
+                if (safe)
+                    this.style.setProperty(`--pb-comments-${name}`, safe);
+                else
+                    this.style.removeProperty(`--pb-comments-${name}`);
+            }
+            const font = safeFont(theme.fontFamily);
+            if (font)
+                this.style.setProperty('--pb-comments-font', font);
+            else
+                this.style.removeProperty('--pb-comments-font');
+            this.style.setProperty('--pb-comments-space', `${safeDimension(theme.spacing, 16, 6, 32)}px`);
+            this.style.setProperty('--pb-comments-radius', `${safeDimension(theme.radius, 16, 0, 32)}px`);
+            this.root.host.toggleAttribute('data-dark', theme.mode === 'dark' || (theme.mode === 'auto' && prefersDark()));
+        }
+        render() {
+            const options = this.currentOptions;
+            if (!options || options.placement === 'headless') {
+                this.root.replaceChildren();
+                return;
+            }
+            const placement = options.placement ?? 'inline';
+            const shell = document.createElement('div');
+            shell.className = `pb-shell pb-${placement}`;
+            if (placement === 'modal' || placement === 'bottom-sheet') {
+                const trigger = button(options.title ?? 'Order comments', 'open');
+                trigger.className = 'pb-trigger';
+                shell.append(trigger);
+                if (this.opened) {
+                    const overlay = document.createElement('div');
+                    overlay.className = `pb-overlay ${placement === 'bottom-sheet' ? 'pb-sheet-overlay' : ''}`;
+                    overlay.setAttribute('role', 'presentation');
+                    overlay.addEventListener('click', (event) => {
+                        if (event.target === overlay)
+                            this.closePanel();
+                    });
+                    const panel = this.makePanel(options.title ?? 'Order comments', true);
+                    panel.classList.add(placement === 'bottom-sheet' ? 'pb-sheet' : 'pb-modal');
+                    overlay.append(panel);
+                    shell.append(overlay);
+                }
+            }
+            else {
+                shell.append(this.makePanel(options.title ?? 'Order comments', false));
+            }
+            this.root.replaceChildren(this.styles(), shell);
+            const open = this.root.querySelector('[data-action="open"]');
+            open?.addEventListener('click', () => {
+                this.opened = true;
+                this.render();
+                void this.load();
+            });
+            this.root.querySelector('[data-action="close"]')?.addEventListener('click', () => this.closePanel());
+            this.root.querySelector('[data-action="refresh"]')?.addEventListener('click', () => void this.load());
+            this.root.querySelector('[data-action="retry"]')?.addEventListener('click', () => void this.load());
+            this.root.querySelector('[data-action="more"]')?.addEventListener('click', () => {
+                if (this.nextCursor)
+                    void this.load(this.nextCursor);
+            });
+            const textarea = this.root.querySelector('textarea');
+            if (textarea) {
+                textarea.value = this.draft;
+                textarea.addEventListener('input', () => {
+                    this.draft = textarea.value;
+                    const send = this.root.querySelector('[data-action="send"]');
+                    if (send)
+                        send.disabled = this.sending || !this.draft.trim();
+                    if (this.pendingText !== this.draft.trim()) {
+                        this.pendingText = null;
+                        this.pendingId = null;
+                    }
+                });
+                textarea.addEventListener('keydown', (event) => {
+                    if (event.key === 'Enter' && !event.shiftKey) {
+                        event.preventDefault();
+                        void this.send();
+                    }
+                });
+            }
+            this.root.querySelector('[data-action="send"]')?.addEventListener('click', () => void this.send());
+            if (!this.currentOptions?.renderMessage) {
+                this.root.querySelectorAll('[data-message]').forEach((node) => {
+                    const message = this.messages.find((item) => item.messageId === node.dataset.message);
+                    if (message)
+                        node.textContent = message.text;
+                });
+            }
+            const list = this.root.querySelector('.pb-messages');
+            if (list && this.messages.length && !this.loading)
+                list.scrollTop = list.scrollHeight;
+        }
+        closePanel() {
+            this.opened = false;
+            this.closeCurrentClient();
+            this.resetConversation();
+            this.render();
+        }
+        makePanel(title, closable) {
+            const panel = document.createElement('section');
+            panel.className = 'pb-panel';
+            if (closable)
+                panel.setAttribute('role', 'dialog');
+            panel.setAttribute('aria-label', title);
+            const header = document.createElement('header');
+            const heading = document.createElement('strong');
+            heading.textContent = title;
+            const headerActions = document.createElement('div');
+            if (this.unreadCount) {
+                const unread = document.createElement('span');
+                unread.className = 'pb-unread';
+                unread.textContent = `${this.unreadCount} unread`;
+                headerActions.append(unread);
+            }
+            const refresh = button('Refresh', 'refresh');
+            refresh.className = 'pb-icon-button';
+            refresh.setAttribute('aria-label', 'Refresh comments');
+            headerActions.append(refresh);
+            if (closable) {
+                const close = button('×', 'close');
+                close.className = 'pb-icon-button';
+                close.setAttribute('aria-label', 'Close comments');
+                headerActions.append(close);
+            }
+            header.append(heading, headerActions);
+            panel.append(header);
+            if (this.loading && !this.messages.length) {
+                const status = document.createElement('div');
+                status.className = 'pb-state';
+                status.setAttribute('role', 'status');
+                status.textContent = 'Loading comments…';
+                panel.append(status);
+            }
+            else if (this.error) {
+                const error = document.createElement('div');
+                error.className = 'pb-error';
+                error.setAttribute('role', 'alert');
+                const copy = document.createElement('p');
+                copy.textContent = this.error;
+                const retry = button(this.expired ? 'Reconnect' : 'Retry', 'retry');
+                error.append(copy, retry);
+                panel.append(error);
+            }
+            else {
+                const list = document.createElement('div');
+                list.className = 'pb-messages';
+                list.setAttribute('aria-live', 'polite');
+                list.setAttribute('aria-busy', String(this.loading));
+                if (this.nextCursor) {
+                    const more = button('Load newer comments', 'more');
+                    more.className = 'pb-more';
+                    list.append(more);
+                }
+                if (!this.messages.length) {
+                    const empty = document.createElement('p');
+                    empty.className = 'pb-empty';
+                    empty.textContent = 'No comments yet. Send a message to the business.';
+                    list.append(empty);
+                }
+                for (const message of this.messages) {
+                    const renderMessage = this.currentOptions?.renderMessage;
+                    if (renderMessage) {
+                        try {
+                            const rendered = renderMessage(message);
+                            if (rendered && rendered.nodeType === 1) {
+                                rendered.dataset.message ??= message.messageId;
+                                list.append(rendered);
+                                continue;
+                            }
+                        }
+                        catch {
+                            // A consumer renderer must not take down the comments conversation.
+                        }
+                    }
+                    const bubble = document.createElement('article');
+                    bubble.className = `pb-bubble ${message.participantSide === 'business' ? 'pb-business' : 'pb-customer'}`;
+                    const who = document.createElement('strong');
+                    who.textContent = message.participantSide === 'business' ? 'Business' : 'Customer';
+                    const text = document.createElement('p');
+                    text.dataset.message = message.messageId;
+                    text.textContent = message.text;
+                    const time = document.createElement('time');
+                    time.dateTime = message.createdAt;
+                    time.textContent = new Date(message.createdAt).toLocaleString(this.currentOptions?.language);
+                    bubble.append(who, text, time);
+                    list.append(bubble);
+                }
+                panel.append(list);
+                const composer = document.createElement('div');
+                composer.className = 'pb-composer';
+                const textarea = document.createElement('textarea');
+                textarea.setAttribute('maxlength', '5000');
+                textarea.setAttribute('aria-label', 'Write a message');
+                textarea.placeholder = 'Write a message';
+                textarea.rows = 2;
+                const send = button(this.sending ? 'Sending…' : 'Send', 'send');
+                send.className = 'pb-send';
+                send.disabled = this.sending || !this.draft.trim();
+                composer.append(textarea, send);
+                panel.append(composer);
+            }
+            return panel;
+        }
+        styles() {
+            const style = document.createElement('style');
+            style.textContent = `
+        :host{display:block;color:var(--pb-comments-text);font:400 14px/1.45 var(--pb-comments-font);--pb-comments-accent:#1b6856;--pb-comments-surface:#fff;--pb-comments-text:#18312b;--pb-comments-muted:#66756f;--pb-comments-border:#dce6e1;--pb-comments-customer:#1b6856;--pb-comments-customer-text:#fff;--pb-comments-business:#eef4f1;--pb-comments-business-text:#18312b;--pb-comments-font:system-ui,sans-serif;--pb-comments-space:16px;--pb-comments-radius:16px}
+        *{box-sizing:border-box}button,textarea{font:inherit}button{cursor:pointer}
+        .pb-panel{display:flex;flex-direction:column;min-height:360px;max-height:76vh;background:var(--pb-comments-surface);color:var(--pb-comments-text);border:1px solid var(--pb-comments-border);border-radius:var(--pb-comments-radius);overflow:hidden;box-shadow:0 10px 35px #10282018}
+        .pb-inline .pb-panel{width:100%}.pb-full-page .pb-panel{height:100%;min-height:70vh;max-height:none}
+        header{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:var(--pb-comments-space);border-bottom:1px solid var(--pb-comments-border)}
+        header strong{font-size:1rem}header div{display:flex;align-items:center;gap:8px}.pb-icon-button{border:0;background:transparent;color:var(--pb-comments-muted);font-size:1.25rem;padding:5px 8px;border-radius:8px}.pb-icon-button:hover{background:var(--pb-comments-business)}
+        .pb-unread{color:var(--pb-comments-accent);font-size:.75rem;font-weight:700}
+        .pb-messages{display:flex;flex:1;flex-direction:column;gap:10px;overflow:auto;padding:var(--pb-comments-space);min-height:120px}
+        .pb-bubble{width:fit-content;max-width:86%;padding:10px 13px;border-radius:14px;overflow-wrap:anywhere}
+        .pb-bubble strong{display:block;margin-bottom:4px;font-size:.72rem;opacity:.72}.pb-bubble p{margin:0;white-space:pre-wrap}.pb-bubble time{display:block;margin-top:6px;font-size:.68rem;opacity:.66}
+        .pb-business{align-self:flex-start;background:var(--pb-comments-business);color:var(--pb-comments-business-text)}.pb-customer{align-self:flex-end;background:var(--pb-comments-customer);color:var(--pb-comments-customer-text)}
+        .pb-composer{display:flex;align-items:flex-end;gap:8px;padding:10px var(--pb-comments-space);border-top:1px solid var(--pb-comments-border)}
+        textarea{flex:1;resize:vertical;min-height:44px;max-height:130px;padding:10px 11px;border:1px solid var(--pb-comments-border);border-radius:10px;background:var(--pb-comments-surface);color:var(--pb-comments-text);outline-color:var(--pb-comments-accent)}
+        .pb-send,.pb-trigger,.pb-error button{border:0;border-radius:9px;background:var(--pb-comments-accent);color:#fff;font-weight:700;padding:10px 14px}.pb-send:disabled{opacity:.55;cursor:not-allowed}
+        .pb-state,.pb-empty,.pb-error{padding:var(--pb-comments-space);color:var(--pb-comments-muted)}.pb-empty{text-align:center;margin:auto}.pb-error{color:var(--pb-comments-text)}.pb-error p{margin:0 0 12px}.pb-error button{padding:8px 12px}
+        .pb-more{align-self:center;border:0;background:transparent;color:var(--pb-comments-accent);font-weight:700;padding:6px 10px}
+        .pb-overlay{position:fixed;z-index:2147483000;inset:0;display:grid;place-items:center;padding:20px;background:#10201dcc}.pb-modal{width:min(560px,100%)}
+        .pb-sheet-overlay{align-items:end;padding:0}.pb-sheet{width:min(720px,100%);max-height:88vh;border-radius:18px 18px 0 0}.pb-trigger{min-height:42px}
+        :host([data-dark]){--pb-comments-surface:#17231f;--pb-comments-text:#eef5f1;--pb-comments-muted:#afbbb5;--pb-comments-border:#35453e;--pb-comments-business:#263a32;--pb-comments-business-text:#eef5f1;--pb-comments-customer:#236b58;--pb-comments-customer-text:#fff}
+      `;
+            return style;
+        }
+    }
+    customElements.define(tagName, PocketBossOrderComments);
+}
+export function mountOrderCommentsElement(element, options) {
+    registerOrderCommentsElement();
+    const target = element;
+    target.options = options;
+    return target;
+}
+function button(label, action) {
+    const value = document.createElement('button');
+    value.type = 'button';
+    value.textContent = label;
+    value.dataset.action = action;
+    return value;
+}
+function contextKey(options) {
+    return `${options.apiBaseUrl}\u0000${options.workspaceKey}\u0000${options.orderId}`;
+}
+function isInitiallyOpen(placement) {
+    return placement !== 'modal' && placement !== 'bottom-sheet' && placement !== 'headless';
+}
+function secureUuid() {
+    if (!globalThis.crypto?.randomUUID)
+        throw new OrderCommentsError('Secure randomness is unavailable.');
+    return globalThis.crypto.randomUUID();
+}
+function safeColor(value) {
+    if (!value || value.length > 64)
+        return null;
+    return /^(#[0-9a-f]{3,8}|rgba?\([0-9., %]+\)|hsla?\([0-9., %deg]+\))$/i.test(value) ? value : null;
+}
+function safeFont(value) {
+    if (!value || value.length > 120 || !/^[a-z0-9 ,"'-]+$/i.test(value))
+        return null;
+    return value;
+}
+function safeDimension(value, fallback, min, max) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+function prefersDark() {
+    return typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: dark)').matches;
+}

package/dist/comments.d.ts

@@ -0,0 +1,57 @@
+export interface OrderCommentsSession {
+    sessionId: string;
+    token: string;
+    expiresAt: string;
+    scopes?: readonly string[];
+}
+export interface OrderCommentMessage {
+    messageId: string;
+    conversationId: string;
+    orderId: string;
+    participantSide: 'customer' | 'business';
+    text: string;
+    deliveryState: 'sent';
+    createdAt: string;
+}
+export interface OrderCommentPage {
+    messages: OrderCommentMessage[];
+    nextCursor: string | null;
+    unreadCount: number;
+}
+export interface OrderCommentsSessionProvider {
+    create(): Promise<OrderCommentsSession>;
+    revoke(sessionId: string): Promise<void>;
+}
+export interface OrderCommentsClientOptions {
+    apiBaseUrl: string;
+    orderId: string;
+    sessions: OrderCommentsSessionProvider;
+    fetcher?: typeof fetch;
+}
+export declare class OrderCommentsError extends Error {
+    readonly status: number | null;
+    readonly code: string | null;
+    constructor(message: string, status?: number | null, code?: string | null);
+}
+/** REST comments transport, independent of the native Mini App bridge. */
+export declare class OrderCommentsClient {
+    private readonly apiBaseUrl;
+    private readonly orderId;
+    private readonly sessions;
+    private readonly fetcher;
+    private session;
+    private openingSession;
+    private closePromise;
+    private pendingRevocationId;
+    private readonly activeRequests;
+    private closed;
+    constructor(options: OrderCommentsClientOptions);
+    get active(): boolean;
+    messages(cursor?: string, limit?: number): Promise<OrderCommentPage>;
+    send(text: string, clientMessageId?: string): Promise<OrderCommentMessage>;
+    markRead(messageId: string): Promise<void>;
+    close(): Promise<void>;
+    private request;
+    private getSession;
+    private revokeSession;
+}

package/dist/comments.js

@@ -0,0 +1,226 @@
+export class OrderCommentsError extends Error {
+    status;
+    code;
+    constructor(message, status = null, code = null) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'OrderCommentsError';
+    }
+}
+/** REST comments transport, independent of the native Mini App bridge. */
+export class OrderCommentsClient {
+    apiBaseUrl;
+    orderId;
+    sessions;
+    fetcher;
+    session = null;
+    openingSession = null;
+    closePromise = null;
+    pendingRevocationId = null;
+    activeRequests = new Set();
+    closed = false;
+    constructor(options) {
+        const base = options.apiBaseUrl.replace(/\/+$/, '');
+        if (!/^https?:\/\//i.test(base) || base.length > 2048) {
+            throw new OrderCommentsError('A valid PocketBoss API base URL is required.');
+        }
+        if (!/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(options.orderId)) {
+            throw new OrderCommentsError('A valid PocketBoss order ID is required.');
+        }
+        this.apiBaseUrl = base;
+        this.orderId = options.orderId;
+        this.sessions = options.sessions;
+        this.fetcher = options.fetcher ?? globalThis.fetch.bind(globalThis);
+    }
+    get active() {
+        return !this.closed;
+    }
+    async messages(cursor, limit = 50) {
+        const query = new URLSearchParams({ limit: String(Math.min(50, Math.max(1, limit))) });
+        if (cursor)
+            query.set('cursor', cursor);
+        const result = await this.request(`/comments/orders/${encodeURIComponent(this.orderId)}/messages?${query}`);
+        const data = record(result.data);
+        if (!Array.isArray(data.messages) || !(data.nextCursor === null || typeof data.nextCursor === 'string') || typeof data.unreadCount !== 'number') {
+            throw new OrderCommentsError('PocketBoss returned an invalid comments page.');
+        }
+        return {
+            messages: data.messages.map(parseMessage),
+            nextCursor: data.nextCursor,
+            unreadCount: data.unreadCount,
+        };
+    }
+    async send(text, clientMessageId = secureUuid()) {
+        const normalizedText = text.trim();
+        if (!normalizedText || normalizedText.length > 5000) {
+            throw new OrderCommentsError('A message from 1 to 5000 characters is required.', 422, 'VALIDATION_FAILED');
+        }
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(clientMessageId)) {
+            throw new OrderCommentsError('A secure idempotency key is required.', 422, 'VALIDATION_FAILED');
+        }
+        const result = await this.request(`/comments/orders/${encodeURIComponent(this.orderId)}/messages`, {
+            method: 'POST',
+            body: JSON.stringify({ client_message_id: clientMessageId, text: normalizedText }),
+        });
+        return parseMessage(result.data);
+    }
+    async markRead(messageId) {
+        if (!/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(messageId)) {
+            throw new OrderCommentsError('A valid comments message ID is required.', 422, 'VALIDATION_FAILED');
+        }
+        await this.request(`/comments/orders/${encodeURIComponent(this.orderId)}/read`, {
+            method: 'POST',
+            body: JSON.stringify({ message_id: messageId }),
+        });
+    }
+    async close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closed = true;
+        const active = this.session;
+        this.session = null;
+        const opening = this.openingSession;
+        for (const controller of this.activeRequests)
+            controller.abort();
+        this.activeRequests.clear();
+        this.closePromise = (async () => {
+            if (active)
+                await this.revokeSession(active.sessionId);
+            if (opening) {
+                try {
+                    await opening;
+                }
+                catch {
+                    if (this.pendingRevocationId)
+                        throw new OrderCommentsError('The comments session could not be revoked during close.', 503, 'COMMENTS_SESSION_CLOSE_FAILED');
+                }
+            }
+            if (this.pendingRevocationId)
+                await this.revokeSession(this.pendingRevocationId);
+        })();
+        return this.closePromise;
+    }
+    async request(path, init = {}, retried = false) {
+        if (this.closed)
+            throw new OrderCommentsError('The order comments session is closed.');
+        const session = await this.getSession();
+        const controller = new AbortController();
+        this.activeRequests.add(controller);
+        const headers = new Headers(init.headers);
+        headers.set('Accept', 'application/json');
+        headers.set('Authorization', `Bearer ${session.token}`);
+        if (init.body !== undefined)
+            headers.set('Content-Type', 'application/json');
+        let response;
+        try {
+            response = await this.fetcher(`${this.apiBaseUrl}${path}`, {
+                ...init,
+                cache: 'no-store',
+                credentials: 'omit',
+                redirect: 'error',
+                referrerPolicy: 'no-referrer',
+                headers,
+                signal: controller.signal,
+            });
+        }
+        catch {
+            if (this.closed)
+                throw new OrderCommentsError('The order comments session is closed.');
+            throw new OrderCommentsError('Could not connect to order comments. Check the connection and retry.');
+        }
+        finally {
+            this.activeRequests.delete(controller);
+        }
+        if ((response.status === 401 || response.status === 410) && !retried) {
+            await this.getSession(true);
+            return this.request(path, init, true);
+        }
+        const body = await response.json().catch(() => null);
+        if (!response.ok) {
+            const error = isRecord(body) && isRecord(body.error) ? body.error : {};
+            throw new OrderCommentsError(typeof error.message === 'string' ? error.message : 'Order comments are unavailable. Retry or sign in again.', response.status, typeof error.code === 'string' ? error.code : null);
+        }
+        if (!isRecord(body) || !isRecord(body.data)) {
+            throw new OrderCommentsError('PocketBoss returned an invalid comments response.');
+        }
+        return body;
+    }
+    async getSession(force = false) {
+        if (this.closed)
+            throw new OrderCommentsError('The order comments session is closed.');
+        if (!force && this.session && this.session.expiresAtMs > Date.now() + 5_000)
+            return this.session;
+        if (this.openingSession)
+            return this.openingSession;
+        this.openingSession = (async () => {
+            const previous = this.session;
+            this.session = null;
+            if (this.pendingRevocationId)
+                await this.revokeSession(this.pendingRevocationId);
+            if (previous) {
+                try {
+                    await this.revokeSession(previous.sessionId);
+                }
+                catch {
+                    throw new OrderCommentsError('The previous comments session could not be closed. Reopen this order after your Mini App session is restored.', 503, 'COMMENTS_SESSION_CLOSE_FAILED');
+                }
+            }
+            let value;
+            try {
+                value = await this.sessions.create();
+            }
+            catch {
+                throw new OrderCommentsError('Your business session expired. Sign in again to renew comments access.', 401, 'COMMENTS_SESSION_EXPIRED');
+            }
+            const expiresAtMs = Date.parse(value.expiresAt);
+            if (typeof value.sessionId !== 'string' || value.sessionId.length < 16 ||
+                typeof value.token !== 'string' || !value.token.startsWith('pbcs_') ||
+                !Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now()) {
+                throw new OrderCommentsError('The Mini App backend returned an invalid comments session.');
+            }
+            const stored = { ...value, expiresAtMs };
+            if (this.closed) {
+                await this.revokeSession(stored.sessionId);
+                throw new OrderCommentsError('The order comments session is closed.');
+            }
+            this.session = stored;
+            return stored;
+        })();
+        try {
+            return await this.openingSession;
+        }
+        finally {
+            this.openingSession = null;
+        }
+    }
+    async revokeSession(sessionId) {
+        this.pendingRevocationId = sessionId;
+        await this.sessions.revoke(sessionId);
+        if (this.pendingRevocationId === sessionId)
+            this.pendingRevocationId = null;
+    }
+}
+function parseMessage(value) {
+    if (!isRecord(value) || typeof value.messageId !== 'string' ||
+        typeof value.conversationId !== 'string' || typeof value.orderId !== 'string' ||
+        (value.participantSide !== 'customer' && value.participantSide !== 'business') ||
+        typeof value.text !== 'string' || value.deliveryState !== 'sent' ||
+        typeof value.createdAt !== 'string' || !Number.isFinite(Date.parse(value.createdAt))) {
+        throw new OrderCommentsError('PocketBoss returned an invalid comment.');
+    }
+    return value;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function record(value) {
+    if (!isRecord(value))
+        throw new OrderCommentsError('PocketBoss returned an invalid comments response.');
+    return value;
+}
+function secureUuid() {
+    if (!globalThis.crypto?.randomUUID)
+        throw new OrderCommentsError('Secure randomness is unavailable.');
+    return globalThis.crypto.randomUUID();
+}

package/dist/index.d.ts

@@ -2,4 +2,8 @@ export { PocketBossClient } from './client.js';
 export { BridgeError } from './types.js';
 export { captureDevicePhoto, pickDeviceFiles } from './media.js';
 export type { CaptureFacingMode, DeviceFilePickerOptions } from './media.js';
+export { OrderCommentsClient, OrderCommentsError } from './comments.js';
+export type { OrderCommentMessage, OrderCommentPage, OrderCommentsClientOptions, OrderCommentsSession, OrderCommentsSessionProvider } from './comments.js';
+export { mountOrderCommentsElement, registerOrderCommentsElement } from './comments-element.js';
+export type { OrderCommentsElementOptions, OrderCommentsPlacement, OrderCommentsTheme, OrderCommentsThemeMode, PocketBossOrderCommentsElement } from './comments-element.js';
 export type { BridgeCapability, BridgeErrorCode, BridgeEvent, BridgeLimits, BridgeMethod, BridgeMethodMap, BridgeSnapshot, BridgeState, BridgeTransport, MethodRequest, MethodResponse, ReadyMessage, RequestOptions } from './types.js';

package/dist/index.js

@@ -1,3 +1,5 @@
 export { PocketBossClient } from './client.js';
 export { BridgeError } from './types.js';
 export { captureDevicePhoto, pickDeviceFiles } from './media.js';
+export { OrderCommentsClient, OrderCommentsError } from './comments.js';
+export { mountOrderCommentsElement, registerOrderCommentsElement } from './comments-element.js';

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@pocketboss/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "publishConfig": { "access": "public" },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./comments": { "types": "./dist/comments/index.d.ts", "default": "./dist/comments/index.js" },
     "./mock": { "types": "./dist/mock.d.ts", "default": "./dist/mock.js" }
   },
   "files": ["dist", "README.md"],