@pocketboss/core 0.2.0 → 0.2.1

package/README.md

@@ -1,67 +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.
 
-const client = new PocketBossClient();
-if (client.isAvailable) {
-  await client.connect();
-  const info = await client.getInfo();
-  console.log(info.platform);
-}
-client.close();
-```
-
-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.
-
-```ts
-import { captureDevicePhoto, pickDeviceFiles } from '@pocketboss/core';
+## Runnable vanilla quickstart
 
-// 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' });
+Requirements: Node.js 24.21.0 and npm 11.19.0. From the repository root:
 
-if (photo) {
-  const form = new FormData();
-  form.append('photo', photo, photo.name);
-  await fetch('/api/photos', { method: 'POST', body: form });
-}
-```
-
-`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`.
+~~~sh
+npm ci
+npm run build:core
+npx vite packages/sdk-core/examples/vanilla --host 127.0.0.1
+~~~
 
-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.
+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.
 
-`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.
+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.
 
-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.
+## Bridge lifecycle
 
-Run `npm run build:core` and `npm test -w @pocketboss/core` from the repository root. Regenerate contract types before every build.
+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.
 
-## Business order comments
+~~~ts
+import { BridgeError, PocketBossClient } from '@pocketboss/core';
 
-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
+const client = new PocketBossClient();
+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;
+}
+window.addEventListener('pagehide', () => client.close(), { once: true });
+~~~
+
+<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.
+
+### Bridge client exports
+
+| 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. |
+
+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';
-import type { OrderCommentMessage, PocketBossOrderCommentsElement } 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') as PocketBossOrderCommentsElement;
+const element = document.querySelector('pb-order-comments')!;
 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;
+  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
+
+From the repository root:
+
+~~~sh
+npm run build:core
+npm test -w @pocketboss/core
+(cd packages/sdk-core && npm pack --dry-run --json)
+~~~
+
+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.
+
+## Developer Portal
 
-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.
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pocketboss/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "publishConfig": { "access": "public" },
   "type": "module",
   "main": "./dist/index.js",