@pocketboss/core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @pocketboss/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```ts
+import { PocketBossClient } from '@pocketboss/core';
+
+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';
+
+// 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' });
+
+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`.
+
+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.
+
+`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 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.

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+import type { BridgeTransport } from './types.js';
+export declare function browserTransport(): BridgeTransport | null;

package/dist/browser.js

@@ -0,0 +1,23 @@
+export function browserTransport() {
+    if (typeof window === 'undefined')
+        return null;
+    const bridge = window.PocketBoss;
+    if (!bridge || typeof bridge.postMessage !== 'function')
+        return null;
+    return {
+        kind: 'native',
+        postMessage(message) { bridge.postMessage(message); },
+        subscribe(listener) {
+            const handler = (event) => listener(event.data);
+            if (bridge.addEventListener && bridge.removeEventListener) {
+                bridge.addEventListener('message', handler);
+                return () => bridge.removeEventListener?.('message', handler);
+            }
+            const previous = bridge.onmessage;
+            const chained = (event) => { previous?.(event); handler(event); };
+            bridge.onmessage = chained;
+            return () => { if (bridge.onmessage === chained)
+                bridge.onmessage = previous; };
+        },
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import type { BridgeEvent, BridgeMethod, BridgeMethodMap, BridgeSnapshot, BridgeTransport, MethodRequest, MethodResponse, ReadyMessage, RequestOptions } from './types.js';
+export declare class PocketBossClient {
+    private readonly transport;
+    private unsubscribeTransport;
+    private readonly stateListeners;
+    private readonly eventListeners;
+    private readonly pending;
+    private handshake;
+    private expiryTimer;
+    private lastSequence;
+    private readyMessage;
+    private state;
+    private currentSnapshot;
+    constructor(transport?: BridgeTransport | null);
+    get isAvailable(): boolean;
+    get isMock(): boolean;
+    get snapshot(): BridgeSnapshot;
+    getSnapshot: () => BridgeSnapshot;
+    subscribeState: (listener: () => void) => (() => void);
+    on(event: string, listener: (event: BridgeEvent) => void): () => void;
+    connect(options?: RequestOptions): Promise<ReadyMessage>;
+    request<M extends BridgeMethod>(method: M, payload: MethodRequest<M>, options?: RequestOptions): Promise<MethodResponse<M>>;
+    getInfo(options?: RequestOptions): Promise<BridgeMethodMap['runtime.getInfo']['response']>;
+    openExternal(url: string, options?: RequestOptions): Promise<BridgeMethodMap['navigation.openExternal']['response']>;
+    closeMiniApp(options?: RequestOptions): Promise<BridgeMethodMap['navigation.close']['response']>;
+    share(payload: BridgeMethodMap['share.open']['request'], options?: RequestOptions): Promise<BridgeMethodMap['share.open']['response']>;
+    pickFiles(payload?: BridgeMethodMap['file.pick']['request'], options?: RequestOptions): Promise<BridgeMethodMap['file.pick']['response']>;
+    capturePhoto(options?: RequestOptions): Promise<BridgeMethodMap['camera.capture']['response']>;
+    getAssertion(options?: RequestOptions): Promise<BridgeMethodMap['identity.getAssertion']['response']>;
+    getCurrentLocation(accuracy: 'approximate' | 'precise', options?: RequestOptions): Promise<BridgeMethodMap['location.getCurrent']['response']>;
+    subscribeNotifications(options?: RequestOptions): Promise<BridgeMethodMap['notifications.subscribe']['response']>;
+    sendNotification(payload: BridgeMethodMap['notifications.send']['request'], options?: RequestOptions): Promise<BridgeMethodMap['notifications.send']['response']>;
+    close(): void;
+    private makeSnapshot;
+    private setState;
+    private send;
+    private receive;
+    private finishHandshake;
+    private finishPending;
+    private expire;
+}

package/dist/client.js

@@ -0,0 +1,328 @@
+import Ajv2020Module from 'ajv/dist/2020.js';
+import addFormatsModule from 'ajv-formats';
+import { browserTransport } from './browser.js';
+import { bridgeSchema, methodSchemas } from './generated/schemas.js';
+import { BridgeError } from './types.js';
+const SDK_VERSION = '0.1.0';
+const MAX_MESSAGE_BYTES = 65_536;
+const ZERO_UUID = '00000000-0000-4000-8000-000000000000';
+const ajv = new Ajv2020Module.default({ strict: true, strictRequired: false });
+addFormatsModule.default(ajv);
+const validMessage = ajv.compile(bridgeSchema);
+const methodValidators = Object.fromEntries(Object.entries(methodSchemas).map(([name, schemas]) => [name, {
+        request: ajv.compile(schemas.request), response: ajv.compile(schemas.result),
+    }]));
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function randomNonce() {
+    const bytes = new Uint8Array(24);
+    if (!globalThis.crypto?.getRandomValues)
+        throw new BridgeError('UNAVAILABLE', 'Secure randomness is unavailable.');
+    globalThis.crypto.getRandomValues(bytes);
+    let value = '';
+    for (const byte of bytes)
+        value += String.fromCharCode(byte);
+    return btoa(value).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+function randomId() {
+    if (!globalThis.crypto?.randomUUID)
+        throw new BridgeError('UNAVAILABLE', 'Secure randomness is unavailable.');
+    return globalThis.crypto.randomUUID();
+}
+function decode(raw) {
+    try {
+        if (typeof raw === 'string') {
+            if (new TextEncoder().encode(raw).length > MAX_MESSAGE_BYTES)
+                return null;
+            const parsed = JSON.parse(raw);
+            return isRecord(parsed) ? parsed : null;
+        }
+        if (isRecord(raw) && new TextEncoder().encode(JSON.stringify(raw)).length <= MAX_MESSAGE_BYTES)
+            return raw;
+    }
+    catch { /* Ignore untrusted messages. */ }
+    return null;
+}
+export class PocketBossClient {
+    transport;
+    unsubscribeTransport = null;
+    stateListeners = new Set();
+    eventListeners = new Map();
+    pending = new Map();
+    handshake = null;
+    expiryTimer = null;
+    lastSequence = -1;
+    readyMessage = null;
+    state;
+    currentSnapshot;
+    constructor(transport = browserTransport()) {
+        this.transport = transport;
+        this.state = transport ? 'idle' : 'unavailable';
+        this.currentSnapshot = this.makeSnapshot();
+        if (transport)
+            this.unsubscribeTransport = transport.subscribe((data) => this.receive(data));
+    }
+    get isAvailable() { return this.transport?.kind === 'native'; }
+    get isMock() { return this.transport?.kind === 'mock'; }
+    get snapshot() { return this.currentSnapshot; }
+    getSnapshot = () => this.currentSnapshot;
+    subscribeState = (listener) => {
+        this.stateListeners.add(listener);
+        return () => { this.stateListeners.delete(listener); };
+    };
+    on(event, listener) {
+        const group = this.eventListeners.get(event) ?? new Set();
+        group.add(listener);
+        this.eventListeners.set(event, group);
+        return () => {
+            group.delete(listener);
+            if (group.size === 0)
+                this.eventListeners.delete(event);
+        };
+    }
+    async connect(options = {}) {
+        if (this.state === 'ready' && this.readyMessage)
+            return this.readyMessage;
+        if (this.handshake)
+            return new Promise((resolve, reject) => {
+                const unsubscribe = this.subscribeState(() => {
+                    if (this.state === 'ready' && this.readyMessage) {
+                        unsubscribe();
+                        resolve(this.readyMessage);
+                    }
+                    else if (this.state !== 'connecting') {
+                        unsubscribe();
+                        reject(new BridgeError(this.state === 'expired' ? 'SESSION_EXPIRED' : 'UNAVAILABLE', 'The bridge is unavailable.'));
+                    }
+                });
+            });
+        if (!this.transport || this.state === 'unavailable' || this.state === 'closed')
+            throw new BridgeError('UNAVAILABLE', 'PocketBoss is unavailable outside the app.');
+        if (this.state === 'expired')
+            throw new BridgeError('SESSION_EXPIRED', 'The launch session expired.');
+        if (options.signal?.aborted)
+            throw new BridgeError('CANCELLED', 'The handshake was cancelled.');
+        this.setState('connecting');
+        return new Promise((resolve, reject) => {
+            const timeoutMs = Math.min(Math.max(options.timeoutMs ?? 15_000, 1_000), 60_000);
+            const fail = (error) => { this.finishHandshake(error); };
+            const onAbort = () => fail(new BridgeError('CANCELLED', 'The handshake was cancelled.'));
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            this.handshake = {
+                resolve, reject,
+                timer: setTimeout(() => fail(new BridgeError('TIMEOUT', 'The bridge handshake timed out.')), timeoutMs),
+                cleanup: () => options.signal?.removeEventListener('abort', onAbort),
+            };
+            try {
+                this.send({ protocolVersion: 1, type: 'hello', sdkVersion: SDK_VERSION, supportedProtocolVersions: [1], clientNonce: randomNonce(), sentAtMs: Date.now() });
+            }
+            catch (error) {
+                fail(error instanceof BridgeError ? error : new BridgeError('UNAVAILABLE', 'The bridge could not send the handshake.'));
+            }
+        });
+    }
+    request(method, payload, options = {}) {
+        if (this.state !== 'ready' || !this.readyMessage)
+            return Promise.reject(new BridgeError(this.state === 'expired' ? 'SESSION_EXPIRED' : 'UNAVAILABLE', 'The bridge is not ready.'));
+        if (Date.now() >= this.readyMessage.sessionExpiresAtMs) {
+            this.expire();
+            return Promise.reject(new BridgeError('SESSION_EXPIRED', 'The launch session expired.'));
+        }
+        const validator = methodValidators[method];
+        if (!validator || !validator.request(payload))
+            return Promise.reject(new BridgeError('INVALID_ARGUMENT', 'The request payload is invalid.'));
+        if (!this.readyMessage.capabilities.some((capability) => capability.name === method && capability.version === 1))
+            return Promise.reject(new BridgeError('NOT_APPROVED', 'This capability is unavailable.'));
+        if (this.pending.size >= this.readyMessage.limits.maxPendingRequests)
+            return Promise.reject(new BridgeError('RATE_LIMITED', 'Too many bridge requests are pending.'));
+        if (options.signal?.aborted)
+            return Promise.reject(new BridgeError('CANCELLED', 'The request was cancelled.'));
+        const requestId = randomId();
+        const request = { protocolVersion: 1, type: 'request', launchId: this.readyMessage.launchId, appId: this.readyMessage.appId, requestId, method, payload, nonce: randomNonce(), sentAtMs: Date.now() };
+        const timeoutMs = Math.min(Math.max(options.timeoutMs ?? this.readyMessage.limits.defaultTimeoutMs, 1_000), 60_000);
+        return new Promise((resolve, reject) => {
+            const onAbort = () => this.finishPending(requestId, new BridgeError('CANCELLED', 'The request was cancelled.'), true);
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            this.pending.set(requestId, {
+                method,
+                resolve: (value) => resolve(value), reject,
+                timer: setTimeout(() => this.finishPending(requestId, new BridgeError('TIMEOUT', 'The bridge request timed out.'), true), timeoutMs),
+                cleanup: () => options.signal?.removeEventListener('abort', onAbort),
+            });
+            try {
+                this.send(request, this.readyMessage.limits.maxMessageBytes);
+            }
+            catch (error) {
+                this.finishPending(requestId, error instanceof BridgeError ? error : new BridgeError('UNAVAILABLE', 'The bridge could not send the request.'));
+            }
+        });
+    }
+    getInfo(options) {
+        return this.request('runtime.getInfo', {}, options);
+    }
+    openExternal(url, options) {
+        return this.request('navigation.openExternal', { url }, options);
+    }
+    closeMiniApp(options) {
+        return this.request('navigation.close', {}, options);
+    }
+    share(payload, options) {
+        return this.request('share.open', payload, options);
+    }
+    pickFiles(payload = {}, options) {
+        return this.request('file.pick', payload, options);
+    }
+    capturePhoto(options) {
+        return this.request('camera.capture', {}, options);
+    }
+    getAssertion(options) {
+        return this.request('identity.getAssertion', {}, options);
+    }
+    getCurrentLocation(accuracy, options) {
+        return this.request('location.getCurrent', { accuracy }, options);
+    }
+    subscribeNotifications(options) {
+        return this.request('notifications.subscribe', {}, options);
+    }
+    sendNotification(payload, options) {
+        return this.request('notifications.send', payload, options);
+    }
+    close() {
+        if (this.state === 'closed')
+            return;
+        this.finishHandshake(new BridgeError('CANCELLED', 'The bridge was closed.'));
+        for (const id of [...this.pending.keys()])
+            this.finishPending(id, new BridgeError('CANCELLED', 'The bridge was closed.'), true);
+        if (this.expiryTimer)
+            clearTimeout(this.expiryTimer);
+        this.unsubscribeTransport?.();
+        this.unsubscribeTransport = null;
+        this.eventListeners.clear();
+        this.setState('closed');
+        this.stateListeners.clear();
+    }
+    makeSnapshot() {
+        return { state: this.state, isAvailable: this.isAvailable, isMock: this.isMock, capabilities: this.readyMessage?.capabilities ?? [], ready: this.readyMessage };
+    }
+    setState(state) {
+        this.state = state;
+        this.currentSnapshot = this.makeSnapshot();
+        for (const listener of this.stateListeners)
+            listener();
+    }
+    send(message, limit = MAX_MESSAGE_BYTES) {
+        if (!this.transport)
+            throw new BridgeError('UNAVAILABLE', 'PocketBoss is unavailable.');
+        const encoded = JSON.stringify(message);
+        if (new TextEncoder().encode(encoded).length > Math.min(limit, MAX_MESSAGE_BYTES))
+            throw new BridgeError('INVALID_ARGUMENT', 'The bridge message is too large.');
+        if (!validMessage(message))
+            throw new BridgeError('INVALID_ARGUMENT', 'The bridge message is invalid.');
+        this.transport.postMessage(encoded);
+    }
+    receive(raw) {
+        const message = decode(raw);
+        if (!message)
+            return;
+        if (message.type === 'ready' && (message.protocolVersion !== 1 || message.selectedProtocolVersion !== 1)) {
+            this.finishHandshake(new BridgeError('UNSUPPORTED_PLATFORM', 'The bridge protocol version is unsupported.'));
+            return;
+        }
+        if (!validMessage(message))
+            return;
+        if (message.type === 'ready') {
+            if (!this.handshake || this.state !== 'connecting')
+                return;
+            const ready = message;
+            if (ready.sessionExpiresAtMs <= Date.now()) {
+                this.finishHandshake(new BridgeError('SESSION_EXPIRED', 'The launch session expired.'));
+                return;
+            }
+            this.readyMessage = ready;
+            this.lastSequence = -1;
+            this.finishHandshake(null, ready);
+            this.expiryTimer = setTimeout(() => this.expire(), Math.min(ready.sessionExpiresAtMs - Date.now(), 2_147_483_647));
+            return;
+        }
+        if (message.type === 'response') {
+            if (message.requestId === ZERO_UUID && this.handshake && message.status === 'error') {
+                const error = message.error;
+                this.finishHandshake(new BridgeError(error.code, error.message, error.details));
+                return;
+            }
+            if (message.launchId !== this.readyMessage?.launchId || typeof message.requestId !== 'string')
+                return;
+            const pending = this.pending.get(message.requestId);
+            if (!pending)
+                return;
+            if (message.status === 'error') {
+                const error = message.error;
+                this.finishPending(message.requestId, new BridgeError(error.code, error.message, error.details));
+                if (error.code === 'SESSION_EXPIRED')
+                    this.expire();
+            }
+            else if (methodValidators[pending.method]?.response(message.result)) {
+                this.finishPending(message.requestId, null, false, message.result);
+            }
+            else {
+                this.finishPending(message.requestId, new BridgeError('INVALID_ARGUMENT', 'The bridge response is invalid.'));
+            }
+            return;
+        }
+        if (message.type === 'event') {
+            const event = message;
+            if (event.launchId !== this.readyMessage?.launchId || event.appId !== this.readyMessage?.appId || event.sequence <= this.lastSequence)
+                return;
+            this.lastSequence = event.sequence;
+            if (event.event === 'lifecycle.pause')
+                for (const id of [...this.pending.keys()])
+                    this.finishPending(id, new BridgeError('CANCELLED', 'The app was paused.'), true);
+            if (event.event === 'lifecycle.expired')
+                this.expire();
+            for (const listener of this.eventListeners.get(event.event) ?? [])
+                listener(event);
+        }
+    }
+    finishHandshake(error, ready) {
+        const handshake = this.handshake;
+        if (!handshake)
+            return;
+        this.handshake = null;
+        clearTimeout(handshake.timer);
+        handshake.cleanup();
+        if (error) {
+            this.setState(error.code === 'SESSION_EXPIRED' ? 'expired' : 'idle');
+            handshake.reject(error);
+        }
+        else if (ready) {
+            this.setState('ready');
+            handshake.resolve(ready);
+        }
+    }
+    finishPending(id, error, cancel = false, result) {
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        pending.cleanup();
+        if (cancel && this.readyMessage) {
+            try {
+                this.send({ protocolVersion: 1, type: 'cancel', launchId: this.readyMessage.launchId, appId: this.readyMessage.appId, requestId: id }, this.readyMessage.limits.maxMessageBytes);
+            }
+            catch { /* Cancellation is best effort. */ }
+        }
+        if (error)
+            pending.reject(error);
+        else
+            pending.resolve(result);
+    }
+    expire() {
+        if (this.state === 'expired' || this.state === 'closed')
+            return;
+        for (const id of [...this.pending.keys()])
+            this.finishPending(id, new BridgeError('SESSION_EXPIRED', 'The launch session expired.'));
+        this.setState('expired');
+    }
+}

package/dist/generated/methods.d.ts

@@ -0,0 +1,96 @@
+export interface BridgeMethodMap {
+    "camera.capture": {
+        request: Record<string, never>;
+        response: {
+            "file": {
+                "handle": string;
+                "name": string;
+                "mimeType": string;
+                "sizeBytes": number;
+                "expiresAtMs": number;
+            };
+        };
+    };
+    "file.pick": {
+        request: {
+            "mimeTypes"?: Array<string>;
+            "multiple"?: boolean;
+        };
+        response: {
+            "files": Array<{
+                "handle": string;
+                "name": string;
+                "mimeType": string;
+                "sizeBytes": number;
+                "expiresAtMs": number;
+            }>;
+        };
+    };
+    "identity.getAssertion": {
+        request: Record<string, never>;
+        response: {
+            "assertion": string;
+            "expiresAtMs": number;
+        };
+    };
+    "location.getCurrent": {
+        request: {
+            "accuracy": "approximate" | "precise";
+        };
+        response: {
+            "latitude": number;
+            "longitude": number;
+            "accuracyMeters": number;
+            "capturedAtMs": number;
+        };
+    };
+    "navigation.close": {
+        request: Record<string, never>;
+        response: {
+            "closed": true;
+        };
+    };
+    "navigation.openExternal": {
+        request: {
+            "url": string;
+        };
+        response: {
+            "opened": true;
+        };
+    };
+    "notifications.send": {
+        request: {
+            "title": string;
+            "body": string;
+            "path"?: string;
+        };
+        response: {
+            "queued": true;
+        };
+    };
+    "notifications.subscribe": {
+        request: Record<string, never>;
+        response: {
+            "subscribed": true;
+        };
+    };
+    "runtime.getInfo": {
+        request: Record<string, never>;
+        response: {
+            "platform": "android" | "ios";
+            "runtimeVersion": string;
+            "protocolVersion": 1;
+        };
+    };
+    "share.open": {
+        request: {
+            "title"?: string;
+            "text"?: string;
+            "url"?: string;
+        };
+        response: {
+            "presented": true;
+        };
+    };
+}
+export type BridgeMethod = keyof BridgeMethodMap;

package/dist/generated/methods.js

@@ -0,0 +1 @@
+export {};