@waler/sdk 0.1.1

package/dist/client/rpc.js

@@ -0,0 +1,94 @@
+import { captureCallSite, sdkError, withCallSite } from "../errors.js";
+import { newId } from "../protocol/ids.js";
+import { timeoutFor as defaultTimeoutFor } from "./timeouts.js";
+/**
+ * One map of in-flight requests, keyed by envelope id, above every transport —
+ * which is why the timeout and the call-site stack live here and not in one.
+ *
+ * Nothing here knows what a window or an origin is: a message that reaches this
+ * point already cleared the transport's gates.
+ */
+export function createRpc(transport, config = {}) {
+    const timeoutFor = config.timeoutFor ?? defaultTimeoutFor;
+    const pending = new Map();
+    const eventHandlers = new Set();
+    const settle = (envelope) => {
+        const entry = pending.get(envelope.id);
+        // An answer that arrived after its own timeout, or one for a request never
+        // made. Both are dropped.
+        if (entry === undefined)
+            return;
+        clearTimeout(entry.timer);
+        pending.delete(envelope.id);
+        if (envelope.kind === 'response') {
+            entry.resolve(envelope.payload);
+            return;
+        }
+        const body = envelope.error;
+        entry.reject(withCallSite(sdkError(body?.code ?? 'INTERNAL', body?.message ?? 'The shell answered with an error.', {
+            method: entry.method,
+            ...(body?.details === undefined ? {} : { details: body.details }),
+        }), entry.callSite));
+    };
+    transport.onMessage((envelope) => {
+        switch (envelope.kind) {
+            case 'response':
+            case 'error':
+                settle(envelope);
+                return;
+            case 'event': {
+                const name = envelope.event;
+                if (name === undefined)
+                    return;
+                for (const handler of eventHandlers)
+                    handler(name, envelope.payload);
+                return;
+            }
+            // The shell asking the app for something is not part of this surface.
+            // Ignored rather than answered.
+            case 'request':
+                return;
+        }
+    });
+    const envelopeFor = (method, payload, id) => ({
+        v: 1,
+        id,
+        /**
+         * One per outbound request, since a request is one user action. It travels
+         * with the message so a single action stays identifiable across every system
+         * that handles it.
+         */
+        correlationId: newId(),
+        kind: 'request',
+        method,
+        ...(payload === undefined ? {} : { payload }),
+    });
+    return {
+        request(method, payload) {
+            // Captured before anything async, while the caller is still on the stack.
+            const callSite = captureCallSite();
+            const id = newId();
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    reject(withCallSite(sdkError('TIMEOUT', `The shell did not answer '${method}' in time.`, { method }), callSite));
+                }, timeoutFor(method));
+                pending.set(id, {
+                    method,
+                    callSite,
+                    timer,
+                    resolve,
+                    reject,
+                });
+                transport.send(envelopeFor(method, payload, id));
+            });
+        },
+        notify(method, payload) {
+            transport.send(envelopeFor(method, payload, newId()));
+        },
+        onEvent(handler) {
+            eventHandlers.add(handler);
+            return () => eventHandlers.delete(handler);
+        },
+    };
+}

package/dist/client/sdk.d.ts

@@ -0,0 +1,7 @@
+import type { RpcConfig } from './rpc.ts';
+import type { BridgeTransport, WalerSDK } from '../types.ts';
+export interface SdkConfig extends RpcConfig {
+    readonly appId: string;
+    readonly surfaceUrl: string;
+}
+export declare function createSdkOver(transport: BridgeTransport, config: SdkConfig): WalerSDK;

package/dist/client/sdk.js

@@ -0,0 +1,100 @@
+import { sdkError } from "../errors.js";
+import { SDK_VERSION } from "../version.js";
+import { createCapabilitySet } from "./capabilities.js";
+import { createEmitter } from "./events.js";
+import { isReadyPayload, isShellContext } from "./ready.js";
+import { createRpc } from "./rpc.js";
+/**
+ * Checked here as well as in the shell: a shell that served a method it never
+ * declared would let an app ship with no fallback, and that app would break
+ * against an older one. `getGeolocation` needs `geolocation` — the method and
+ * the capability are named differently, and this is the only place that knows.
+ */
+const CAPABILITY_BY_METHOD = {
+    notify: 'notify',
+    download: 'download',
+    share: 'share',
+    scanBarcode: 'scanBarcode',
+    getGeolocation: 'geolocation',
+};
+export function createSdkOver(transport, config) {
+    const rpc = createRpc(transport, config);
+    const emitter = createEmitter();
+    const capabilities = createCapabilitySet();
+    let context = null;
+    const ready = (async () => {
+        const answer = await rpc.request('setup', {
+            appId: config.appId,
+            url: config.surfaceUrl,
+            sdkVersion: SDK_VERSION,
+        });
+        if (!isReadyPayload(answer)) {
+            throw sdkError('INTERNAL', 'The shell answered the handshake with a malformed ReadyPayload.', {
+                method: 'setup',
+                details: answer,
+            });
+        }
+        capabilities.replace(answer.capabilities);
+        context = answer.context;
+        return answer;
+    })();
+    // An app may never await `ready` at all. Without a handler here, the
+    // NOT_IN_SHELL of the standalone path would surface as an unhandled rejection.
+    // This swallows nothing: the app's own `await` still rejects.
+    void ready.catch(() => { });
+    rpc.onEvent((event, payload) => {
+        // `context` is kept in step before the app's handlers run, so a handler that
+        // reads `Waler.context` sees the change it was told about rather than the
+        // one before it.
+        if (event === 'contextchange' && isShellContext(payload)) {
+            context = payload;
+        }
+        if (event === 'audiencechange' && context !== null) {
+            const change = payload;
+            if (typeof change.activeAudience === 'string' && Array.isArray(change.audiences)) {
+                context = {
+                    ...context,
+                    activeAudience: change.activeAudience,
+                    audiences: change.audiences,
+                };
+            }
+        }
+        emitter.emit(event, payload);
+    });
+    /**
+     * Every call waits for the handshake, so failures report their real cause and a
+     * capability check never runs against a list that is not filled in yet.
+     */
+    const call = async (method, payload) => {
+        await ready;
+        const required = CAPABILITY_BY_METHOD[method];
+        if (required !== undefined && !capabilities.view.has(required)) {
+            throw sdkError('UNSUPPORTED', `This shell does not offer '${required}'. Check capabilities.has('${required}') before calling '${method}'.`, { method });
+        }
+        return rpc.request(method, payload);
+    };
+    // These return void, so they cannot report a failed handshake. Sending them
+    // after `ready` keeps them ordered behind it; with no shell they are dropped.
+    const tell = (method, payload) => {
+        void ready.then(() => rpc.notify(method, payload), () => undefined);
+    };
+    return {
+        ready,
+        get context() {
+            return context;
+        },
+        capabilities: capabilities.view,
+        getToken: (request) => call('getToken', request),
+        openApp: (key, params) => call('openApp', { key, ...(params === undefined ? {} : { params }) }),
+        navigate: (path) => tell('navigate', { path }),
+        close: (result) => tell('close', { result }),
+        setHeader: (state) => tell('setHeader', state),
+        notify: (options) => call('notify', options),
+        download: (options) => call('download', options),
+        share: (options) => call('share', options),
+        scanBarcode: () => call('scanBarcode'),
+        getGeolocation: () => call('getGeolocation'),
+        on: (event, handler) => emitter.on(event, handler),
+        invoke: (method, payload) => call(method, payload),
+    };
+}

package/dist/client/timeouts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Split by who is being waited on, not by method: a request the shell answers
+ * itself cannot share a budget with one that waits on a person, or the timeout
+ * that is useful for the first cancels a legitimate action in the second.
+ *
+ * Neither bucket is unbounded — nothing may hang without eventually reporting.
+ */
+export declare const REQUEST_TIMEOUT_MS = 10000;
+/** Long enough for a slow shell to boot, short enough that a blocked frame says so. */
+export declare const HANDSHAKE_TIMEOUT_MS = 15000;
+export declare const USER_ACTION_TIMEOUT_MS = 300000;
+export declare function timeoutFor(method: string): number;

package/dist/client/timeouts.js

@@ -0,0 +1,17 @@
+/**
+ * Split by who is being waited on, not by method: a request the shell answers
+ * itself cannot share a budget with one that waits on a person, or the timeout
+ * that is useful for the first cancels a legitimate action in the second.
+ *
+ * Neither bucket is unbounded — nothing may hang without eventually reporting.
+ */
+export const REQUEST_TIMEOUT_MS = 10_000;
+/** Long enough for a slow shell to boot, short enough that a blocked frame says so. */
+export const HANDSHAKE_TIMEOUT_MS = 15_000;
+export const USER_ACTION_TIMEOUT_MS = 300_000;
+const USER_DRIVEN = new Set(['openApp', 'scanBarcode', 'getGeolocation', 'share']);
+export function timeoutFor(method) {
+    if (method === 'setup')
+        return HANDSHAKE_TIMEOUT_MS;
+    return USER_DRIVEN.has(method) ? USER_ACTION_TIMEOUT_MS : REQUEST_TIMEOUT_MS;
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+import type { SdkError, SdkErrorCode } from './types.ts';
+interface SdkErrorInit {
+    readonly method?: string;
+    readonly details?: unknown;
+}
+export declare function sdkError(code: SdkErrorCode, message: string, init?: SdkErrorInit): SdkError;
+/**
+ * An error arriving over the bridge is built inside a message listener, so its
+ * own stack points at the listener and is the same for every failure. The frame
+ * worth having is the `await` that started the call, so it is captured on the way
+ * out and transplanted onto the error on the way back.
+ *
+ * Above the transports on purpose: one that had to remember to do this would be
+ * the one nobody can debug.
+ */
+export declare function captureCallSite(): Error;
+export declare function withCallSite(error: SdkError, callSite: Error): SdkError;
+export {};

package/dist/errors.js

@@ -0,0 +1,38 @@
+class WalerSdkError extends Error {
+    code;
+    method;
+    details;
+    constructor(code, message, init = {}) {
+        super(message);
+        this.name = 'SdkError';
+        this.code = code;
+        // Assigned conditionally rather than unconditionally: with
+        // exactOptionalPropertyTypes an explicit `undefined` is not the same as an
+        // absent key, and `'method' in error` is a check an app can reasonably make.
+        if (init.method !== undefined)
+            this.method = init.method;
+        if (init.details !== undefined)
+            this.details = init.details;
+    }
+}
+export function sdkError(code, message, init = {}) {
+    return new WalerSdkError(code, message, init);
+}
+/**
+ * An error arriving over the bridge is built inside a message listener, so its
+ * own stack points at the listener and is the same for every failure. The frame
+ * worth having is the `await` that started the call, so it is captured on the way
+ * out and transplanted onto the error on the way back.
+ *
+ * Above the transports on purpose: one that had to remember to do this would be
+ * the one nobody can debug.
+ */
+export function captureCallSite() {
+    return new Error('waler-sdk call site');
+}
+export function withCallSite(error, callSite) {
+    const frames = callSite.stack?.split('\n').slice(1) ?? [];
+    if (frames.length > 0)
+        error.stack = [`${error.name}: ${error.message}`, ...frames].join('\n');
+    return error;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { WalerSDK, WalerSdkOptions } from './types.ts';
+export type { Audience, BridgeEnvelope, BridgeTransport, Capability, CapabilitySet, DownloadOptions, GeolocationResult, HeaderState, KnownCapability, KnownSdkErrorCode, NotifyOptions, Platform, PlatformEndpoints, ReadyPayload, ScanResult, SdkError, SdkErrorCode, SdkEventMap, ShareOptions, ShellContext, ThemeTokens, TokenRequest, TokenResult, Unsubscribe, WalerSDK, WalerSdkOptions, } from './types.ts';
+/**
+ * Builds the SDK and starts the handshake.
+ *
+ * ```ts
+ * const Waler = createSdk({ appId: 'my-app', allowedOrigins: ['https://shell.example.com'] })
+ * const { api, context } = await Waler.ready
+ * ```
+ *
+ * The handshake starts here rather than on import, so nothing goes on the wire
+ * because a bundler included the module. Inside a frame this uses the iframe
+ * bridge; outside one, everything rejects with NOT_IN_SHELL.
+ */
+export declare function createSdk(options: WalerSdkOptions): WalerSDK;

package/dist/index.js

@@ -0,0 +1,21 @@
+import { surfaceUrl } from "./browser.js";
+import { selectTransport } from "./bridge/select.js";
+import { createSdkOver } from "./client/sdk.js";
+/**
+ * Builds the SDK and starts the handshake.
+ *
+ * ```ts
+ * const Waler = createSdk({ appId: 'my-app', allowedOrigins: ['https://shell.example.com'] })
+ * const { api, context } = await Waler.ready
+ * ```
+ *
+ * The handshake starts here rather than on import, so nothing goes on the wire
+ * because a bundler included the module. Inside a frame this uses the iframe
+ * bridge; outside one, everything rejects with NOT_IN_SHELL.
+ */
+export function createSdk(options) {
+    return createSdkOver(selectTransport(options), {
+        appId: options.appId,
+        surfaceUrl: surfaceUrl(),
+    });
+}

package/dist/protocol/ids.d.ts

@@ -0,0 +1 @@
+export declare function newId(): string;

package/dist/protocol/ids.js

@@ -0,0 +1,15 @@
+/**
+ * Ids only have to be unique within one page's in-flight requests, so this is not
+ * a security primitive and must not be used as one. The fallback exists because
+ * `crypto` is unavailable outside a secure context.
+ */
+const randomId = () => `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+export function newId() {
+    const c = globalThis.crypto;
+    if (typeof c === 'object' && c !== null && 'randomUUID' in c) {
+        const uuid = c.randomUUID;
+        if (typeof uuid === 'function')
+            return uuid.call(c);
+    }
+    return randomId();
+}

package/dist/protocol/wire.d.ts

@@ -0,0 +1,22 @@
+import type { BridgeEnvelope } from '../types.ts';
+/**
+ * Read before parsing. A surface's window receives every postMessage aimed at it,
+ * and without a marker readable up front each one would have to be deserialised
+ * to discover it was never ours — a parser pointed at input from anywhere.
+ */
+export declare const WIRE_PREFIX = "waler:v1:";
+/**
+ * A string on every transport, so the prefix above can be checked before parsing
+ * and so a bridge that only carries strings needs no second format.
+ *
+ * No checksum by design: a non-cryptographic one detects neither the corruption
+ * that cannot happen here nor any tampering, and carrying one would imply an
+ * integrity guarantee this envelope does not have. Origin validation is it.
+ */
+export declare function encode(envelope: BridgeEnvelope): string;
+/**
+ * `null` for anything that is not ours. Never throws: the caller is a message
+ * listener, and an exception there would surface as an unhandled error in the
+ * page, triggered by input a stranger controls.
+ */
+export declare function decode(raw: unknown): BridgeEnvelope | null;

package/dist/protocol/wire.js

@@ -0,0 +1,69 @@
+/**
+ * Read before parsing. A surface's window receives every postMessage aimed at it,
+ * and without a marker readable up front each one would have to be deserialised
+ * to discover it was never ours — a parser pointed at input from anywhere.
+ */
+export const WIRE_PREFIX = 'waler:v1:';
+/**
+ * A string on every transport, so the prefix above can be checked before parsing
+ * and so a bridge that only carries strings needs no second format.
+ *
+ * No checksum by design: a non-cryptographic one detects neither the corruption
+ * that cannot happen here nor any tampering, and carrying one would imply an
+ * integrity guarantee this envelope does not have. Origin validation is it.
+ */
+export function encode(envelope) {
+    return WIRE_PREFIX + JSON.stringify(envelope);
+}
+const KINDS = new Set(['request', 'response', 'error', 'event']);
+const isFilledString = (value) => typeof value === 'string' && value.length > 0;
+const isOptionalString = (value) => value === undefined || isFilledString(value);
+/**
+ * `null` for anything that is not ours. Never throws: the caller is a message
+ * listener, and an exception there would surface as an unhandled error in the
+ * page, triggered by input a stranger controls.
+ */
+export function decode(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    if (!raw.startsWith(WIRE_PREFIX))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.slice(WIRE_PREFIX.length));
+    }
+    catch {
+        return null;
+    }
+    return isEnvelope(parsed) ? parsed : null;
+}
+function isEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const e = value;
+    if (e['v'] !== 1)
+        return false;
+    if (!isFilledString(e['id']))
+        return false;
+    if (!isFilledString(e['correlationId']))
+        return false;
+    if (!KINDS.has(e['kind']))
+        return false;
+    if (!isOptionalString(e['method']))
+        return false;
+    if (!isOptionalString(e['event']))
+        return false;
+    // An error envelope with no body would reject a promise with `undefined`,
+    // which from the app's side is indistinguishable from a hang.
+    if (e['kind'] === 'error' && !isErrorBody(e['error']))
+        return false;
+    if (e['kind'] === 'event' && !isFilledString(e['event']))
+        return false;
+    return true;
+}
+function isErrorBody(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const body = value;
+    return isFilledString(body['code']) && typeof body['message'] === 'string';
+}