@pocketboss/core 0.1.0 → 0.2.1

package/README.md

@@ -1,41 +1,220 @@
 # @pocketboss/core
 
-Framework-neutral PocketBoss bridge client and browser file controls for web mini-apps. The bridge client implements the candidate v1 contract; the native host advertises only methods it supports and the backend has approved.
+Framework-neutral TypeScript client for PocketBoss Bridge protocol v1. It provides the vanilla JavaScript entry point, typed bridge requests, browser file inputs, and the shared REST client and custom element for order comments.
 
-```ts
-import { PocketBossClient } from '@pocketboss/core';
+The npm packages are not yet released to the public registry. Use the repository workspace quickstart below for a runnable local app. Public installation is available after the package release gates in the [SDK publishing guide](https://github.com/benogroupltd/PocketBoss/blob/main/docs/SDK_PUBLISHING.md) are satisfied.
+
+## Runnable vanilla quickstart
+
+Requirements: Node.js 24.21.0 and npm 11.19.0. From the repository root:
+
+~~~sh
+npm ci
+npm run build:core
+npx vite packages/sdk-core/examples/vanilla --host 127.0.0.1
+~~~
+
+Open <http://127.0.0.1:5173>. The fixture reports standalone browser mode. Open <http://127.0.0.1:5173/?mock=1> to exercise its explicit mock handler. The mock is only a development response; it does not demonstrate a native permission or authenticated launch.
+
+After a public release, install with <code>npm install @pocketboss/core</code>. Import from <code>@pocketboss/core</code>, <code>@pocketboss/core/comments</code>, or <code>@pocketboss/core/mock</code>. The same package can be used by any JavaScript framework.
+
+## Bridge lifecycle
+
+Create one client for the Mini App document. Connect after startup, check each launch's capabilities before showing a host action, and close the client when the document is destroyed.
+
+~~~ts
+import { BridgeError, PocketBossClient } from '@pocketboss/core';
 
 const client = new PocketBossClient();
-if (client.isAvailable) {
-  await client.connect();
-  const info = await client.getInfo();
-  console.log(info.platform);
+try {
+  const ready = await client.connect();
+  if (ready.capabilities.some((item) =>
+    item.name === 'runtime.getInfo' && item.version === 1)) {
+    const info = await client.getInfo({ timeoutMs: 5000 });
+    document.querySelector('#status')!.textContent =
+      info.platform + ' ' + info.runtimeVersion;
+  }
+} catch (error) {
+  const code = error instanceof BridgeError ? error.code : 'INTERNAL';
+  document.querySelector('#status')!.textContent = 'Bridge error: ' + code;
 }
-client.close();
-```
+window.addEventListener('pagehide', () => client.close(), { once: true });
+~~~
 
-Use browser file controls for ordinary user-selected files and photos. These are standard HTML file inputs exposed as helpers; they do not call `file.pick` or `camera.capture` on the PocketBoss bridge.
+<code>isAvailable</code> is false in a normal browser; <code>isMock</code> identifies an explicitly supplied mock transport. <code>connect()</code> rejects with <code>UNAVAILABLE</code> outside a native host, <code>TIMEOUT</code> when the handshake expires, <code>CANCELLED</code> when its signal is aborted, and <code>UNSUPPORTED_PLATFORM</code> when the host protocol is incompatible. A successful handshake returns the launch, app, release, runtime, capability, limits, and expiry context.
 
-```ts
-import { captureDevicePhoto, pickDeviceFiles } from '@pocketboss/core';
+### Bridge client exports
 
-// Call from a click/tap handler so the browser can present its native chooser.
-const files = await pickDeviceFiles({ accept: 'image/*', multiple: true });
-const photo = await captureDevicePhoto({ facingMode: 'environment' });
+| Export | Parameters and return value | Errors and behavior |
+| --- | --- | --- |
+| <code>PocketBossClient</code> | <code>new PocketBossClient(transport?: BridgeTransport \| null)</code>; defaults to the browser transport. | A null or missing host produces unavailable state. |
+| <code>isAvailable</code>, <code>isMock</code>, <code>snapshot</code>, <code>getSnapshot()</code> | Read native/mock availability or a <code>BridgeSnapshot</code> containing state, capabilities, and ready message. | Snapshot is empty until ready; getters do not connect. |
+| <code>subscribeState(listener: () =&gt; void)</code> | Returns an unsubscribe function. Listener reads the latest snapshot. | No network request. |
+| <code>on(event, listener)</code> | Event name string and <code>(BridgeEvent) =&gt; void</code>; returns unsubscribe function. | Unknown event names simply receive no event. |
+| <code>connect(options?: RequestOptions)</code> | Resolves <code>Promise&lt;ReadyMessage&gt;</code>; default timeout 15 seconds, clamped to 1–60 seconds. | Rejects with <code>BridgeError</code>; see error codes below. |
+| <code>request(method, payload, options?)</code> | Method is a <code>BridgeMethod</code>; payload and <code>Promise&lt;MethodResponse&lt;M&gt;&gt;</code> are inferred from the method map. | Rejects for invalid payload, missing capability, consent/permission denial, expiry, timeout, cancellation, host error, message/pending limits, or unavailable host. |
+| <code>getInfo(options?)</code> | <code>Promise&lt;{platform: 'android' \| 'ios'; runtimeVersion: string; protocolVersion: 1}&gt;</code>. | Requires <code>runtime.getInfo@1</code>. |
+| <code>openExternal(url, options?)</code> | URL string; <code>Promise&lt;{opened: true}&gt;</code>. | Requires an approved <code>navigation.openExternal@1</code> capability and an approved URL origin. |
+| <code>closeMiniApp(options?)</code> | <code>Promise&lt;{closed: true}&gt;</code>; asks the native shell to close this Mini App. | Requires <code>navigation.close@1</code>. This is distinct from local <code>close()</code>. |
+| <code>share(payload, options?)</code> | Optional <code>title</code>, <code>text</code>, <code>url</code>; resolves <code>{presented: true}</code>. | Requires <code>share.open@1</code>; user dismissing the native sheet is not a bridge error. |
+| <code>pickFiles(payload?, options?)</code> | Optional <code>mimeTypes: string[]</code>, <code>multiple: boolean</code>; resolves file handle metadata. | Requires <code>file.pick@1</code>; currently not advertised by native. Use browser <code>pickDeviceFiles</code> for actual file content. |
+| <code>capturePhoto(options?)</code> | Resolves <code>{file: {handle, name, mimeType, sizeBytes, expiresAtMs}}</code>. | Requires <code>camera.capture@1</code>; currently not advertised by native. Use browser <code>captureDevicePhoto</code> for a <code>File</code>. |
+| <code>getAssertion(options?)</code> | Resolves <code>{assertion, expiresAtMs}</code> with a short-lived customer identity assertion. | Requires <code>identity.getAssertion@1</code> and user consent. It does not prove business ownership or staff authority. |
+| <code>getCurrentLocation(accuracy, options?)</code> | Accuracy is <code>'approximate' \| 'precise'</code>; resolves latitude, longitude, accuracy in meters, and capture time. | Requires <code>location.getCurrent@1</code>, approval, and platform permission. Device validation remains a release gate. |
+| <code>subscribeNotifications(options?)</code> | Resolves <code>{subscribed: true}</code>. | Typed but not advertised by the current native host. App-scoped subscription and delivery are not implemented. |
+| <code>sendNotification(payload, options?)</code> | Required title/body and optional path; resolves <code>{queued: true}</code>. | Typed but not advertised by the current native host; do not treat it as a push service. |
+| <code>close()</code> | No parameters; returns <code>void</code>. | Idempotently stops listeners, clears state, and rejects pending work with <code>CANCELLED</code>. It does not log the user out of the Mini App backend. |
 
-if (photo) {
-  const form = new FormData();
-  form.append('photo', photo, photo.name);
-  await fetch('/api/photos', { method: 'POST', body: form });
-}
-```
+Bridge method request and response contracts are:
+
+| Method | Request | Response |
+| --- | --- | --- |
+| <code>runtime.getInfo</code> | <code>{}</code> | platform, runtimeVersion, protocolVersion |
+| <code>navigation.openExternal</code> | <code>{url: string}</code> | <code>{opened: true}</code> |
+| <code>navigation.close</code> | <code>{}</code> | <code>{closed: true}</code> |
+| <code>share.open</code> | optional title, text, url | <code>{presented: true}</code> |
+| <code>identity.getAssertion</code> | <code>{}</code> | assertion and expiry in epoch milliseconds |
+| <code>location.getCurrent</code> | accuracy: approximate or precise | latitude, longitude, accuracyMeters, capturedAtMs |
+| <code>file.pick</code> | optional mimeTypes and multiple | file handle metadata array |
+| <code>camera.capture</code> | <code>{}</code> | one file handle and metadata |
+| <code>notifications.subscribe</code> | <code>{}</code> | <code>{subscribed: true}</code> |
+| <code>notifications.send</code> | title, body, optional path | <code>{queued: true}</code> |
+
+An SDK method being typed does not mean a host exposes it. Runtime info, external navigation, close, share, and identity have Android/iOS handlers but still depend on release approval and, for identity, consent. Location is implemented but its device validation is pending. File/camera and notifications are not advertised. Payments are not part of this SDK.
+
+### Bridge types and error behavior
+
+The public type exports are <code>BridgeCapability</code> ({name, version}), <code>BridgeLimits</code> ({maxMessageBytes, maxPendingRequests, defaultTimeoutMs}), <code>ReadyMessage</code> ({protocolVersion, type, launchId, appId, releaseId, runtimeVersion, selectedProtocolVersion, capabilities, limits, serverTimeMs, sessionExpiresAtMs}), <code>BridgeEvent</code> ({protocolVersion, type, launchId, appId, event, sequence, payload}), <code>BridgeSnapshot</code> ({state, isAvailable, isMock, capabilities, ready}), <code>BridgeState</code> (unavailable, idle, connecting, ready, expired, closed), <code>BridgeTransport</code>, <code>BridgeMethod</code>, <code>BridgeMethodMap</code>, <code>MethodRequest&lt;M&gt;</code>, <code>MethodResponse&lt;M&gt;</code>, and <code>RequestOptions</code> ({signal?, timeoutMs?}). They describe the v1 handshake, events, launch-scoped state, text transport, generated method payloads/results, and cancellation/timeout options. A custom transport implements <code>kind: 'native' | 'mock'</code>, <code>postMessage(serializedMessage)</code>, and <code>subscribe(listener)</code>; application code should normally use the default transport.
+
+<code>BridgeError</code> extends <code>Error</code> and exposes <code>code: BridgeErrorCode</code> and optional structured <code>details</code>. The stable codes are <code>UNAVAILABLE</code>, <code>UNSUPPORTED_PLATFORM</code>, <code>NOT_DECLARED</code>, <code>NOT_APPROVED</code>, <code>CONSENT_REQUIRED</code>, <code>DENIED</code>, <code>CANCELLED</code>, <code>TIMEOUT</code>, <code>INVALID_ARGUMENT</code>, <code>RATE_LIMITED</code>, <code>SESSION_EXPIRED</code>, and <code>INTERNAL</code>. Check the code, not message text. Never auto-retry a denied request. A cancelled request may already have reached the native host.
+
+### Browser media exports
+
+| Export | Parameters and return value | Errors and behavior |
+| --- | --- | --- |
+| <code>CaptureFacingMode</code> | Type union <code>'user' \| 'environment'</code>. | Browser and OS may ignore the camera preference. |
+| <code>DeviceFilePickerOptions</code> | Optional <code>accept</code> (browser input accept string), <code>multiple</code>, and <code>capture</code>. | These are HTML input hints, not bridge capabilities or authorization. |
+| <code>pickDeviceFiles(options?)</code> | Returns <code>Promise&lt;File[]&gt;</code>; call directly from a click/tap handler. | Cancellation resolves <code>[]</code>; unavailable document/input failure rejects. |
+| <code>captureDevicePhoto({facingMode?})</code> | Returns <code>Promise&lt;File \| null&gt;</code>. | Cancellation resolves null; capture is best effort and a chooser may appear. |
+
+Files are normal browser <code>File</code> objects. The Mini App backend still validates size, type, authentication, and authorization.
+
+## Order comments
+
+Comments use PocketBoss REST APIs, independently of the native bridge. The Mini App backend authenticates its owner/staff user, checks active membership and order access, then obtains a short-lived order-scoped session from PocketBoss. The browser receives only that scoped token. Never put a long-lived integration credential in JavaScript or a widget option.
+
+The widget's <code>orderId</code> is the canonical PocketBoss order ULID returned after server-side order synchronization, not the Mini App's external order ID. The backend maps the external ID to that ULID before creating a session. <code>workspaceKey</code> is a UI/context key; it is not proof of a business or staff identity.
+
+~~~ts
+import { registerOrderCommentsElement } from '@pocketboss/core/comments';
+
+const sessions = {
+  async create() {
+    const response = await fetch('/api/business/order-comments/session', {
+      method: 'POST',
+      credentials: 'same-origin',
+      cache: 'no-store',
+      headers: {
+        'Content-Type': 'application/json',
+        'Idempotency-Key': crypto.randomUUID(),
+      },
+      body: JSON.stringify({ externalOrderId: 'shop-order-2048' }),
+    });
+    if (!response.ok) throw new Error('Could not authorize comments.');
+    return response.json();
+  },
+  async revoke(sessionId: string) {
+    const response = await fetch('/api/business/order-comments/session', {
+      method: 'DELETE',
+      credentials: 'same-origin',
+      cache: 'no-store',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId }),
+    });
+    if (!response.ok) throw new Error('Could not revoke comments session.');
+  },
+};
+
+registerOrderCommentsElement();
+const element = document.querySelector('pb-order-comments')!;
+element.options = {
+  apiBaseUrl: 'https://api.example.test/api/v1',
+  orderId: pocketBossOrderId,
+  workspaceKey: businessId,
+  sessions,
+  placement: 'inline',
+  renderMessage(message) {
+    const node = document.createElement('article');
+    node.textContent = message.text;
+    return node;
+  },
+};
+~~~
+
+The route names above are the sample Mini App backend's example, not SDK-managed routes. Adapt the callback to your authenticated same-origin server and its actual route.
+
+### Comments client exports and results
+
+| Export | Parameters and return value | Errors and behavior |
+| --- | --- | --- |
+| <code>OrderCommentsSession</code> | {sessionId, token, expiresAt, scopes?}; expiry is an ISO date string. | Client rejects missing/invalid ID, non-<code>pbcs_</code> token, or expired value. |
+| <code>OrderCommentsSessionProvider</code> | <code>create(): Promise&lt;OrderCommentsSession&gt;</code>; <code>revoke(sessionId: string): Promise&lt;void&gt;</code>. | Create failure becomes <code>COMMENTS_SESSION_EXPIRED</code>; revoke failure is surfaced during close. |
+| <code>OrderCommentsClientOptions</code> | Required <code>apiBaseUrl</code>, PocketBoss <code>orderId</code>, <code>sessions</code>; optional Fetch-compatible <code>fetcher</code> for tests. | Constructor rejects malformed URL or non-ULID order ID. |
+| <code>OrderCommentMessage</code> | messageId, conversationId, orderId, participantSide customer/business, text, deliveryState sent, createdAt ISO string. | Malformed server response rejects with <code>OrderCommentsError</code>. |
+| <code>OrderCommentPage</code> | messages, nextCursor or null, unreadCount. | Malformed page rejects. |
+| <code>OrderCommentsError</code> | Extends <code>Error</code>; exposes <code>status: number \| null</code> and <code>code: string \| null</code>. | Network, HTTP, JSON shape, validation and session failures use this type. |
+| <code>OrderCommentsClient(options)</code> | Owns one order-scoped REST session; lazy session creation; <code>active</code> is a boolean getter. | Does not grant access; backend and PocketBoss authorize every session/request. |
+| <code>messages(cursor?, limit = 50)</code> | Returns <code>Promise&lt;OrderCommentPage&gt;</code>; limit is clamped to 1–50. | HTTP and invalid response errors reject. |
+| <code>send(text, clientMessageId?)</code> | Trims text, 1–5000 characters; optional UUID idempotency key; returns <code>Promise&lt;OrderCommentMessage&gt;</code>. | Invalid text/key rejects 422; default key requires secure browser randomness. |
+| <code>markRead(messageId)</code> | PocketBoss message ULID; returns <code>Promise&lt;void&gt;</code>. | Invalid ID rejects 422; HTTP errors reject. |
+| <code>close()</code> | Returns <code>Promise&lt;void&gt;</code>; aborts requests and invokes session revoke. | Rejects with <code>COMMENTS_SESSION_CLOSE_FAILED</code> when a session cannot be revoked. Treat a failed close as protected content still blocked. |
+
+On HTTP 401 or 410 the client requests a replacement session and retries once. Other non-2xx responses preserve server <code>status</code> and error <code>code</code>. Network failure rejects with <code>OrderCommentsError</code>. The bearer is memory-only, requests omit ambient credentials and redirects, and no session is written to browser storage.
+
+### Comments custom-element exports
+
+| Export | Parameters and return value | Errors and behavior |
+| --- | --- | --- |
+| <code>OrderCommentsPlacement</code> | <code>inline</code>, <code>modal</code>, <code>bottom-sheet</code>, <code>full-page</code>, <code>headless</code>. | Modal and bottom sheet open on user action; headless supplies only the client. |
+| <code>OrderCommentsThemeMode</code>, <code>OrderCommentsTheme</code> | mode light/dark/auto; optional accent, surface, text, muted, border, customer/business bubble and text colors, fontFamily, spacing, radius. | Presentation only; no effect on authorization. |
+| <code>OrderCommentsElementOptions</code> | Client options plus required <code>workspaceKey</code>, optional placement/theme/title/language and <code>renderMessage(message): HTMLElement</code>. | Constructor/client validation errors surface through the client/element. Render user text with <code>textContent</code>, never HTML interpolation. |
+| <code>registerOrderCommentsElement(tagName = 'pb-order-comments')</code> | Returns <code>void</code>; idempotent and safe during SSR. | No-op when custom elements are unavailable. |
+| <code>mountOrderCommentsElement(element, options)</code> | Mounts typed options and returns <code>PocketBossOrderCommentsElement</code>. | Client/session errors surface from load/open methods. |
+| <code>PocketBossOrderCommentsElement</code> | <code>options</code> setter/getter; <code>commentsClient</code> getter; <code>loadComments(): Promise&lt;void&gt;</code>; <code>openCommentsClient(): Promise&lt;OrderCommentsClient&gt;</code>. | Reading options before setting them throws; load/open reject for session/API failures. |
+
+### Mock exports
+
+Import <code>MockBridgeTransport</code>, <code>createMockTransport</code>, <code>MockHandlers</code>, and <code>MockHostOptions</code> from <code>@pocketboss/core/mock</code>. Provide a v1 <code>ready</code> message and typed method handlers. <code>createMockTransport(options)</code> returns a transport with <code>kind: 'mock'</code>; it always reports <code>isMock</code> true and native <code>isAvailable</code> false. Missing handlers reject <code>NOT_APPROVED</code>; unrecognized handler failures map to <code>INTERNAL</code>. Use only in local development and tests.
+
+## Authentication, access modes, orders, and security
+
+The SDK does not sign users in, select a business workspace, register a business, bind staff identities, synchronize orders, or verify server assertions. Keep these responsibilities in the Mini App backend and PocketBoss APIs:
+
+| Access mode | Backend responsibility |
+| --- | --- |
+| Guest | Permit only public guest behavior; guest SSO session lookup may return 401. |
+| Personal | Read the same-origin PocketBoss SSO session and use the app-pairwise subject. |
+| Business | Validate the selected workspace and current PocketBoss roles for each protected action. |
+| Mixed | Authorize each route/action from the backend session; never infer a mode from a query string or browser-supplied business ID. |
+
+Customer <code>identity.getAssertion</code> is an optional, consented bridge capability. Send the unmodified assertion to your same-origin backend for PocketBoss verification; do not decode it and trust its claims. It does not establish business ownership or staff authority. Business registration needs verified ownership, and staff access needs a verified invitation/identity binding. Order writes use a signed server-to-server integration, an app-scoped customer reference, source versions, idempotency, and a transactional outbox. Keep the PocketBoss order ULID for comments.
+
+Call the Mini App backend's logout endpoint and await server revocation when ending or switching an authenticated workspace, then clear the workspace WebView storage according to the host contract. <code>client.close()</code> releases only this SDK client; it does not clear cookies, backend sessions, or native WebView state.
+
+The integration private key, signing material, and long-lived PocketBoss credential stay on the server. Use HTTPS, least-privilege scopes, nonce/timestamp replay protection, idempotency, rotation, audit logging, and current membership checks. See [Authentication](https://pocket-boss.beno.co.tz/developer/identity/authentication), [business registration](https://pocket-boss.beno.co.tz/developer/business/registration), [server integration](https://pocket-boss.beno.co.tz/developer/integration/server-api), [orders](https://pocket-boss.beno.co.tz/developer/orders/synchronization), and [comments](https://pocket-boss.beno.co.tz/developer/messaging/order-comments).
+
+## Build, test, and package contents
 
-`pickDeviceFiles()` returns browser `File` objects and resolves to `[]` on cancellation. `captureDevicePhoto()` returns the first selected image or `null`; `capture` is a best-effort hint and the OS may show a chooser instead of opening a camera. React, Vue, Angular, and Ionic mini-apps can import these helpers from `@pocketboss/core`.
+From the repository root:
 
-The bridge methods `client.pickFiles()` and `client.capturePhoto()` remain separate and gated. They return short-lived opaque handles and are unavailable until the runtime has a supported consumer for those handles.
+~~~sh
+npm run build:core
+npm test -w @pocketboss/core
+(cd packages/sdk-core && npm pack --dry-run --json)
+~~~
 
-`isAvailable` is `false` in a normal browser and in explicit mock mode. `connect()` rejects with `BridgeError('UNAVAILABLE')` when no host exists. The SDK never creates a native result by itself. `@pocketboss/core/mock` supplies an explicit development host whose handlers are provided by the developer.
+The package whitelist is <code>dist</code> plus this README; npm adds package metadata. Inspect the dry-run file list after building. It does not publish. The npm manifest currently has no approved license metadata or license file, so this archive is not publication-ready; resolve the project license decision before a release.
 
-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.
+## Developer Portal
 
-Run `npm run build:core` and `npm test -w @pocketboss/core` from the repository root. Regenerate contract types before every build.
+Continue with the [Vanilla JavaScript guide](https://pocket-boss.beno.co.tz/developer/sdk/vanilla), [bridge reference](https://pocket-boss.beno.co.tz/developer/bridge/capabilities), [quickstart](https://pocket-boss.beno.co.tz/developer/getting-started/quickstart), and the identity, business, orders, and comments guides linked above.

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.1",
   "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"],