@waler/sdk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @waler/sdk
+
+The SDK a Waler app embeds. A Waler app is a web page that a Waler shell loads in
+an iframe; this package is how that page talks to the shell — session, context,
+tokens, navigation, device capabilities and events, over one bridge that behaves
+the same wherever the shell runs.
+
+TypeScript, ESM, **no runtime dependencies**. Works with React, Vue, Svelte or
+plain HTML — the SDK has no opinion about your framework.
+
+## Install
+
+```bash
+npm install @waler/sdk
+```
+
+## Quickstart
+
+```ts
+import { createSdk } from '@waler/sdk'
+
+const Waler = createSdk({
+  // Your app's registered id.
+  appId: 'my-app',
+  // The shell origins allowed to host this surface. A security boundary, not
+  // configuration — see "Origins" below.
+  allowedOrigins: ['https://tenant-one.example.com'],
+})
+
+// Resolves once the shell has answered. From here on, `context` is filled in
+// and `capabilities` is populated.
+const { api, context, theme, locale } = await Waler.ready
+
+console.log(context.tenantId, context.userId, context.activeAudience)
+```
+
+`ready` rejects rather than resolving half-way. If it resolves, you have a live
+bridge and a real context; you never have to null-check what it returned.
+
+## Calling the platform API
+
+The app never hardcodes the API address. The shell hands it over in the
+handshake, because the same app runs inside many shells on different domains,
+and the same deploy serves dev, staging and production.
+
+```ts
+const { api } = await Waler.ready
+const { token } = await Waler.getToken()
+
+const response = await fetch(`${api.baseUrl}/v1/some-resource`, {
+  headers: { Authorization: `Bearer ${token}` },
+})
+```
+
+`api.issuer` is there so your own backend can validate that token by discovering
+the JWKS from it, instead of shipping a key in its code.
+
+## Feature detection, never version comparison
+
+Your app is inside several shells at once, each on a different version, while the
+app itself is always on its latest deploy. So ask what the shell _can do_, never
+what version it is.
+
+```ts
+if (Waler.capabilities.has('scanBarcode')) {
+  const { value } = await Waler.scanBarcode()
+  fillField(value)
+} else {
+  showManualEntryField()
+}
+```
+
+`ready` returns a `shellVersion`. It is for telemetry. Gating a feature on it is
+a bug that only shows up in the tenants that have not updated.
+
+Capability-gated methods — `notify`, `download`, `share`, `scanBarcode`,
+`getGeolocation` — reject with `UNSUPPORTED` if you call them without checking.
+
+## Origins
+
+`allowedOrigins` is the trust boundary, and the only thing standing between your
+surface and a page that embedded it without permission.
+
+- These are the **only** origins the SDK will send to, each addressed explicitly.
+- Messages from any other origin are dropped silently, before anything reads them.
+- **There is no wildcard.** `'*'` and `'https://*.example.com'` are both refused —
+  the first is not an origin, the second matches nothing and would leave you with
+  an allowlist you believe covers every tenant and that in fact covers none.
+- An allowlist with nothing usable in it fails immediately with
+  `INVALID_ARGUMENT`, rather than hanging until the handshake times out.
+
+List the shell origins of the tenants your app is installed in:
+
+```ts
+createSdk({
+  appId: 'my-app',
+  allowedOrigins: ['https://tenant-one.example.com', 'https://tenant-two.example.com'],
+})
+```
+
+## Events
+
+```ts
+const off = Waler.on('contextchange', (context) => {
+  // The shell resolved a different context, without reloading the surface.
+  render(context)
+})
+
+// Call `off()` when your view goes away.
+```
+
+| Event              | When                                                             |
+| ------------------ | ---------------------------------------------------------------- |
+| `contextchange`    | the shell resolved a different context                           |
+| `audiencechange`   | the user switched to another population                          |
+| `commandupdate`    | a write this app started has a result                            |
+| `themechange`      | the tenant's theme changed, or the system toggled dark mode      |
+| `localechange`     | language or timezone changed                                     |
+| `visibilitychange` | the surface left or came back — **pause polling when invisible** |
+| `tokenexpiring`    | call `getToken()` before it fails                                |
+
+Two things to assume about `commandupdate`, because writes are asynchronous:
+**it may never arrive** (rebuild state when your view opens), and **it may arrive
+twice** (handle it idempotently, keyed on `commandId`). Without both, a
+"processing…" spinner can run forever with no error anywhere.
+
+## Errors
+
+Everything rejects with an `SdkError` carrying a `code`:
+
+```ts
+import type { SdkError } from '@waler/sdk'
+
+try {
+  await Waler.scanBarcode()
+} catch (error) {
+  const { code } = error as SdkError
+  if (code === 'UNSUPPORTED') showManualEntryField()
+  else if (code === 'CANCELLED') return
+  else throw error
+}
+```
+
+| Code               | Meaning                                                        |
+| ------------------ | -------------------------------------------------------------- |
+| `UNSUPPORTED`      | this shell does not offer the method or capability — fall back |
+| `FORBIDDEN`        | not granted in the manifest, or denied                         |
+| `CANCELLED`        | the user backed out                                            |
+| `TIMEOUT`          | the shell did not answer in time                               |
+| `INVALID_ARGUMENT` | bad input, including an unusable `allowedOrigins`              |
+| `NOT_IN_SHELL`     | running outside the shell                                      |
+| `INTERNAL`         | everything else                                                |
+
+Treat the list as open: a newer shell may send a code this version has never
+heard of, and it reaches you unchanged rather than flattened. Always keep an
+`else`.
+
+The stack on these errors points at **your** `await`, not at the SDK's internals.
+
+## Running without a shell
+
+Open your app directly in a browser tab and the SDK falls back to a null
+transport: everything rejects with `NOT_IN_SHELL`. That is a designed path, not
+a failure — it is how you develop and test without standing up a shell.
+
+```ts
+import type { SdkError } from '@waler/sdk'
+
+try {
+  const { context } = await Waler.ready
+  render(context)
+} catch (error) {
+  if ((error as SdkError).code === 'NOT_IN_SHELL') render(mockContext)
+  else throw error
+}
+```
+
+## Surface
+
+| Member                     |                                                             |
+| -------------------------- | ----------------------------------------------------------- |
+| `ready`                    | `Promise<ReadyPayload>` — resolves only over a live bridge  |
+| `context`                  | current `ShellContext`, or `null` before `ready` resolves   |
+| `capabilities`             | `.has(name)` and `.list()`                                  |
+| `getToken(request?)`       | an audience-scoped token                                    |
+| `openApp(key, params?)`    | opens another surface, resolves with what it returned       |
+| `navigate(path)`           | tells the shell your current route, for deep links and back |
+| `close(result?)`           | closes this surface, resolving whoever opened it            |
+| `setHeader(state)`         | title, badge, or hide the native header                     |
+| `on(event, handler)`       | returns an unsubscribe function                             |
+| `invoke(method, payload?)` | escape hatch for methods newer than this SDK                |
+
+`navigate()` and `setHeader()` are explicit on purpose: the SDK does not patch
+`history.pushState` or watch `<title>` to infer them, because it will not rewrite
+globals it does not own inside your app.
+
+Everything is typed. `ReadyPayload`, `ShellContext`, `SdkError`, `Capability`,
+`SdkEventMap` and the rest are exported from the package root.
+
+## Requirements
+
+Any browser the shell supports. Node 20+ if you import it in a build step.
+Published as ESM only, with no runtime dependencies.

package/dist/bridge/iframe.d.ts

@@ -0,0 +1,23 @@
+import type { BridgeTransport } from '../types.ts';
+/**
+ * Everything this transport needs from the browser, injected rather than reached
+ * for — no ambient global and no `MessageEvent` in any signature, so the same
+ * interface is implementable off the web and testable without a browser.
+ */
+export interface FrameMessage {
+    readonly origin: string;
+    readonly data: unknown;
+    readonly source: unknown;
+}
+export interface FrameHost {
+    readonly parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    };
+    addEventListener(type: 'message', listener: (event: FrameMessage) => void): void;
+    removeEventListener(type: 'message', listener: (event: FrameMessage) => void): void;
+}
+export interface IframeTransportOptions {
+    readonly host: FrameHost;
+    readonly allowedOrigins: readonly string[];
+}
+export declare function createIframeTransport(options: IframeTransportOptions): BridgeTransport;

package/dist/bridge/iframe.js

@@ -0,0 +1,103 @@
+import { decode, encode } from "../protocol/wire.js";
+import { createRejectingTransport } from "./rejecting.js";
+/**
+ * Normalises each entry to the exact string `event.origin` will carry, so a
+ * trailing slash or a capital cannot produce an allowlist that matches nothing.
+ *
+ * The wildcard check is NOT redundant with the parse. `'*'` is not a URL and
+ * throws, but `'https://*.example.com'` parses and hands the wildcard back as an
+ * origin — matching no real origin, which is worse than a hole: an allowlist the
+ * developer believes is broad and that in fact covers nobody.
+ */
+function serialisedOrigins(entries) {
+    const origins = new Set();
+    for (const entry of entries) {
+        let url;
+        try {
+            url = new URL(entry);
+        }
+        catch {
+            continue;
+        }
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            continue;
+        if (url.hostname.includes('*'))
+            continue;
+        origins.add(url.origin);
+    }
+    return [...origins];
+}
+export function createIframeTransport(options) {
+    const allowed = serialisedOrigins(options.allowedOrigins);
+    // Fail closed and say what is wrong, instead of a handshake that times out
+    // against a shell that was never at fault.
+    if (allowed.length === 0) {
+        return createRejectingTransport('web', 'INVALID_ARGUMENT', 'createSdk({ allowedOrigins }) has no usable origin. Each entry must be an absolute origin, such as "https://acme.waler.app"; wildcards are not accepted.');
+    }
+    const { host } = options;
+    const handlers = new Set();
+    // Fixed by the first accepted message. Before the handshake any allowed origin
+    // could be the host; after it, exactly one is, and the rest stop being
+    // accepted or posted to.
+    let shellOrigin = null;
+    const listener = (event) => {
+        // GATE 1 — the trust boundary. Discarded in silence, before anything
+        // downstream can hold state about it: no answer, no error, no entry in the
+        // pending map. An unlisted sender learns nothing, not even that it was
+        // refused.
+        if (!allowed.includes(event.origin))
+            return;
+        if (shellOrigin !== null && event.origin !== shellOrigin)
+            return;
+        // GATE 2 — additional, never a substitute. `event.source` says which window
+        // sent the message, not which origin it is from; a sibling frame on an
+        // allowed origin clears gate 1 and has no business speaking for the shell.
+        if (event.source !== host.parent)
+            return;
+        // GATE 3 — the prefix, read off the raw value, before any parsing.
+        const envelope = decode(event.data);
+        if (envelope === null)
+            return;
+        shellOrigin ??= event.origin;
+        for (const handler of handlers)
+            handler(envelope);
+    };
+    let attached = false;
+    const attach = () => {
+        if (attached)
+            return;
+        host.addEventListener('message', listener);
+        attached = true;
+    };
+    const detach = () => {
+        if (!attached)
+            return;
+        host.removeEventListener('message', listener);
+        attached = false;
+    };
+    return {
+        platform: 'web',
+        connected: true,
+        /**
+         * One explicit `targetOrigin` per send, never `'*'`. Until the shell answers
+         * the SDK does not know which allowed origin hosts it, so the handshake goes
+         * to each under its own target — the browser delivers only the copy that
+         * matches and drops the rest. After the answer there is one target.
+         */
+        send(envelope) {
+            const wire = encode(envelope);
+            const targets = shellOrigin === null ? allowed : [shellOrigin];
+            for (const target of targets)
+                host.parent.postMessage(wire, target);
+        },
+        onMessage(handler) {
+            handlers.add(handler);
+            attach();
+            return () => {
+                handlers.delete(handler);
+                if (handlers.size === 0)
+                    detach();
+            };
+        },
+    };
+}

package/dist/bridge/null.d.ts

@@ -0,0 +1,6 @@
+import type { BridgeTransport } from '../types.ts';
+/**
+ * The transport used when the app is not inside a shell. Everything rejects with
+ * NOT_IN_SHELL, which an app can branch on to fall back to mocks.
+ */
+export declare function createNullTransport(): BridgeTransport;

package/dist/bridge/null.js

@@ -0,0 +1,8 @@
+import { createRejectingTransport } from "./rejecting.js";
+/**
+ * The transport used when the app is not inside a shell. Everything rejects with
+ * NOT_IN_SHELL, which an app can branch on to fall back to mocks.
+ */
+export function createNullTransport() {
+    return createRejectingTransport('standalone', 'NOT_IN_SHELL', 'The app is running outside the Waler shell.');
+}

package/dist/bridge/rejecting.d.ts

@@ -0,0 +1,11 @@
+import type { BridgeTransport, Platform, SdkErrorCode } from '../types.ts';
+/**
+ * Answers every request with the same error, and never with silence — a hung
+ * promise has no stack, no log and no timeout. It answers through the same
+ * envelope path as a real transport, which is why nothing above it needs a
+ * branch for it.
+ *
+ * Deferred to a microtask: a synchronous answer would resolve a promise from
+ * inside the `send()` that created it, and no real transport does that.
+ */
+export declare function createRejectingTransport(platform: Platform, code: SdkErrorCode, message: string): BridgeTransport;

package/dist/bridge/rejecting.js

@@ -0,0 +1,36 @@
+/**
+ * Answers every request with the same error, and never with silence — a hung
+ * promise has no stack, no log and no timeout. It answers through the same
+ * envelope path as a real transport, which is why nothing above it needs a
+ * branch for it.
+ *
+ * Deferred to a microtask: a synchronous answer would resolve a promise from
+ * inside the `send()` that created it, and no real transport does that.
+ */
+export function createRejectingTransport(platform, code, message) {
+    const handlers = new Set();
+    return {
+        platform,
+        connected: false,
+        send(envelope) {
+            if (envelope.kind !== 'request')
+                return;
+            const answer = {
+                v: 1,
+                id: envelope.id,
+                correlationId: envelope.correlationId,
+                kind: 'error',
+                ...(envelope.method === undefined ? {} : { method: envelope.method }),
+                error: { code, message },
+            };
+            queueMicrotask(() => {
+                for (const handler of handlers)
+                    handler(answer);
+            });
+        },
+        onMessage(handler) {
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+    };
+}

package/dist/bridge/select.d.ts

@@ -0,0 +1,8 @@
+import type { BridgeTransport, WalerSdkOptions } from '../types.ts';
+/**
+ * ORDER MATTERS. On a mobile device a surface is still inside a frame, so
+ * `detectFrameHost()` answers yes there too — a native check belongs above this
+ * one, never below, or the device silently gets the web bridge and loses its
+ * native capabilities with nothing failing.
+ */
+export declare function selectTransport(options: WalerSdkOptions): BridgeTransport;

package/dist/bridge/select.js

@@ -0,0 +1,16 @@
+import { detectFrameHost } from "../browser.js";
+import { createIframeTransport } from "./iframe.js";
+import { createNullTransport } from "./null.js";
+/**
+ * ORDER MATTERS. On a mobile device a surface is still inside a frame, so
+ * `detectFrameHost()` answers yes there too — a native check belongs above this
+ * one, never below, or the device silently gets the web bridge and loses its
+ * native capabilities with nothing failing.
+ */
+export function selectTransport(options) {
+    const host = detectFrameHost();
+    if (host !== null) {
+        return createIframeTransport({ host, allowedOrigins: options.allowedOrigins });
+    }
+    return createNullTransport();
+}

package/dist/browser.d.ts

@@ -0,0 +1,12 @@
+import type { FrameHost } from './bridge/iframe.ts';
+/**
+ * The one file that reads an ambient browser global; eslint blocks them
+ * everywhere else, which is what keeps the transports portable.
+ */
+/** `null` when not framed, which is what selects the null transport. */
+export declare function detectFrameHost(): FrameHost | null;
+/**
+ * Sent in the handshake so the shell knows which surface is speaking. It is NOT a
+ * trust signal — a page can claim any URL. `event.origin` is what is checked.
+ */
+export declare function surfaceUrl(): string;

package/dist/browser.js

@@ -0,0 +1,21 @@
+/**
+ * The one file that reads an ambient browser global; eslint blocks them
+ * everywhere else, which is what keeps the transports portable.
+ */
+/** `null` when not framed, which is what selects the null transport. */
+export function detectFrameHost() {
+    if (typeof window === 'undefined')
+        return null;
+    if (window.parent === window)
+        return null;
+    return window;
+}
+/**
+ * Sent in the handshake so the shell knows which surface is speaking. It is NOT a
+ * trust signal — a page can claim any URL. `event.origin` is what is checked.
+ */
+export function surfaceUrl() {
+    if (typeof window === 'undefined')
+        return '';
+    return window.location.href;
+}

package/dist/client/capabilities.d.ts

@@ -0,0 +1,10 @@
+import type { Capability, CapabilitySet } from '../types.ts';
+export interface MutableCapabilitySet {
+    readonly view: CapabilitySet;
+    replace(capabilities: readonly Capability[]): void;
+}
+/**
+ * Empty until the handshake fills it. `has()` answering false before then is the
+ * safe reading: an app that checks too early takes its fallback path.
+ */
+export declare function createCapabilitySet(): MutableCapabilitySet;

package/dist/client/capabilities.js

@@ -0,0 +1,16 @@
+/**
+ * Empty until the handshake fills it. `has()` answering false before then is the
+ * safe reading: an app that checks too early takes its fallback path.
+ */
+export function createCapabilitySet() {
+    let capabilities = [];
+    return {
+        view: {
+            has: (capability) => capabilities.includes(capability),
+            list: () => capabilities,
+        },
+        replace(next) {
+            capabilities = [...next];
+        },
+    };
+}

package/dist/client/events.d.ts

@@ -0,0 +1,6 @@
+import type { SdkEventMap, Unsubscribe } from '../types.ts';
+export interface Emitter {
+    on<K extends keyof SdkEventMap>(event: K, handler: (payload: SdkEventMap[K]) => void): Unsubscribe;
+    emit(event: string, payload: unknown): void;
+}
+export declare function createEmitter(): Emitter;

package/dist/client/events.js

@@ -0,0 +1,36 @@
+export function createEmitter() {
+    const handlers = new Map();
+    return {
+        on(event, handler) {
+            const set = handlers.get(event) ?? new Set();
+            handlers.set(event, set);
+            set.add(handler);
+            return () => {
+                set.delete(handler);
+            };
+        },
+        /**
+         * An unknown event name finds no handler and stops here, so a newer shell
+         * cannot break an older app.
+         *
+         * A handler that throws takes neither the others nor the message listener
+         * with it. Rethrowing from a microtask puts the error in front of the page's
+         * own reporting instead of blaming the bridge.
+         */
+        emit(event, payload) {
+            const set = handlers.get(event);
+            if (set === undefined)
+                return;
+            for (const handler of [...set]) {
+                try {
+                    handler(payload);
+                }
+                catch (error) {
+                    queueMicrotask(() => {
+                        throw error;
+                    });
+                }
+            }
+        },
+    };
+}

package/dist/client/ready.d.ts

@@ -0,0 +1,11 @@
+import type { ReadyPayload, ShellContext } from '../types.ts';
+export declare function isShellContext(value: unknown): value is ShellContext;
+/**
+ * What makes `ready` resolving mean something. Without this check a shell that
+ * answered `{}` would leave `context` null right after `await ready` — the
+ * intermittent null the guarantee exists to prevent.
+ *
+ * Shape only, never meaning: `capabilities` may hold names this package has
+ * never heard of and `platform` may gain values. Neither is an error.
+ */
+export declare function isReadyPayload(value: unknown): value is ReadyPayload;

package/dist/client/ready.js

@@ -0,0 +1,50 @@
+const isFilledString = (value) => typeof value === 'string' && value.length > 0;
+const asRecord = (value) => typeof value === 'object' && value !== null ? value : null;
+export function isShellContext(value) {
+    const context = asRecord(value);
+    if (context === null)
+        return false;
+    if (!isFilledString(context['tenantId']))
+        return false;
+    if (!isFilledString(context['userId']))
+        return false;
+    if (!isFilledString(context['activeAudience']))
+        return false;
+    const audiences = context['audiences'];
+    // Never empty: the shell guarantees `activeAudience` belongs to `audiences`,
+    // and an empty list is a context no surface can render under.
+    return Array.isArray(audiences) && audiences.length > 0 && audiences.every(isFilledString);
+}
+/**
+ * What makes `ready` resolving mean something. Without this check a shell that
+ * answered `{}` would leave `context` null right after `await ready` — the
+ * intermittent null the guarantee exists to prevent.
+ *
+ * Shape only, never meaning: `capabilities` may hold names this package has
+ * never heard of and `platform` may gain values. Neither is an error.
+ */
+export function isReadyPayload(value) {
+    const payload = asRecord(value);
+    if (payload === null)
+        return false;
+    if (!isFilledString(payload['shellVersion']))
+        return false;
+    if (!isFilledString(payload['platform']))
+        return false;
+    if (!isFilledString(payload['locale']))
+        return false;
+    if (!isFilledString(payload['timeZone']))
+        return false;
+    const api = asRecord(payload['api']);
+    // The one field an app has no way to recover on its own, and a surface that
+    // resolved without it would fail later, at the first request, far from here.
+    if (api === null || !isFilledString(api['baseUrl']) || !isFilledString(api['issuer'])) {
+        return false;
+    }
+    const capabilities = payload['capabilities'];
+    if (!Array.isArray(capabilities) || !capabilities.every(isFilledString))
+        return false;
+    if (asRecord(payload['theme']) === null)
+        return false;
+    return isShellContext(payload['context']);
+}

package/dist/client/rpc.d.ts

@@ -0,0 +1,20 @@
+import type { BridgeTransport, Unsubscribe } from '../types.ts';
+export type EventHandler = (event: string, payload: unknown) => void;
+export interface Rpc {
+    request<T>(method: string, payload?: unknown): Promise<T>;
+    /** Fire and forget: `navigate`, `close` and `setHeader` return void by contract. */
+    notify(method: string, payload?: unknown): void;
+    onEvent(handler: EventHandler): Unsubscribe;
+}
+export interface RpcConfig {
+    /** Overridable so a test can prove the TIMEOUT path without waiting ten seconds for it. */
+    readonly timeoutFor?: (method: string) => number;
+}
+/**
+ * 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 declare function createRpc(transport: BridgeTransport, config?: RpcConfig): Rpc;