@web-applets/sdk 0.0.4

package/README.md

@@ -0,0 +1,157 @@
+# Web Applets
+
+> An open SDK to create interoperable actions & views for agents – _a web of capabilities!_
+
+## What is it?
+
+Web Applets is a specification for modular, local web software that can be read and used by both humans and machines. Web Applets aims to be an interoperabe application layer for agents – instead of chatbots that can only interact in plain text, Web Applets allow them to actuate real software, read the results, and render rich, graphical views in response.
+
+Did we mention it's _interoperable_? We think the future of software should be open & collaborative, not locked down to a single platform.
+
+## Getting started
+
+First, clone this repo and run `npm run install`. There are a few sample applets included in `/applets`. To install these applets and start the playground, run `npm run playground`.
+
+The fastest way to create a new applet is by duplicating one of the applet folders in `/applets`. The folder title will be part of the URL of your applet, so make sure it doesn't include any spaces or other non-URL-safe characters.
+
+Inside your applet folder, you'll find a basic web app setup:
+
+- `public/manifest.json`: This file describes the Applet, and tells the model what actions are available and what parameters each action takes
+- `index.html`: Much like a website, this holds the main page for your applet
+- `main.js`: Declares functions that respond to each action, and a render function that updates the view based on state
+
+> Want to use React? Svelte? Vue? – No problem, just install the dependencies and create an app the way you normally would in a website. So long as you're receiving the action events, it will all just work.
+
+Let's say we want our applet to respond to a "set_name" action and render the user's name. In our `manifest.json` file we can write:
+
+```js
+{
+  // ...
+  "actions": [
+    {
+      "id": "set_name",
+      "description": "Sets the name of the user to be greeted",
+      "params": {
+        "name": {
+          "type": "string",
+          "description": "The name of the user"
+        }
+      }
+    }
+  ]
+}
+```
+
+Now let's update `main.ts` to assign an action handler:
+
+```js
+// First, import the SDK
+import { appletContext } from '../../sdk/src';
+
+// Now connect to the applet runtime
+const applet = appletContext.connect();
+
+// Attach the action handler, and update the state
+applet.setActionHandler('set_name', ({ name }) => {
+  applet.setState({ name });
+});
+```
+
+When this state updates, it will inform the client which can then store the state somewhere, for example in a database so the applet will persist between uses.
+
+Finally, we need to render the applet whenever a render signal is received. Again in `main.ts`:
+
+```js
+// ...
+
+applet.onrender = () => {
+  document.body.innerText = `Hello, ${applet.state.name}!`;
+};
+```
+
+Now if you run `npm run playground` from the project root, you should be able to test out your new applet action directly. This applet will now work in any environment where the SDK is installed.
+
+![A screenshot showing the 'playground' editing UI, with a web applets showing 'Hello, Web Applets'](docs/assets/web-applets-playground.png)
+
+## Integrating Web Applets into your client
+
+Integrating Web Applets is just as easy as creating one. First, in your project, make sure you have the sdk installed:
+
+```bash
+npm install @unternet/web-applets
+```
+
+In your code, you can import the applets client:
+
+```js
+import { applets } from '@unternet/web-applets';
+```
+
+Now you can create a new applet from a URL:
+
+```js
+const applet = await applets.load(
+  `https://unternet.co/applets/helloworld.applet`
+);
+applet.onstateupdated = (state) => console.log(state);
+applet.dispatchAction('set_name', { name: 'Web Applets' });
+// console.log: { name: "Web Applets" }
+```
+
+The above applet is actually running headless, but we can get it to display by attaching it to an iframe. For the loading step, instead run:
+
+```js
+const container = document.createElement('iframe');
+document.body.appendChild(container);
+const applet = await applets.load(
+  `https://unternet.co/applets/helloworld.applet`,
+  container
+);
+```
+
+To load pre-existing saved state into an applet, simply set the state property:
+
+```js
+applet.state = { name: 'Ada Lovelace' };
+// console.log: { name: "Ada Lovelace" }
+```
+
+It may also be helpful to check available applets at a domain, or in your local public folder if you've downloaded a set of Web Applets you want your product to use. For that you can extract the applet headers from the App Manifest at the public root (`/manifest.json`), and see the available applets and a shorthand for the actions you can take in them. This is automatically created when you build your applets.
+
+```js
+const headers = await applets.getHeaders('/');
+```
+
+This headers object looks like:
+
+```js
+[
+  {
+    name: 'Hello World',
+    description: 'Displays a greeting to the user.',
+    url: '/applets/helloworld.applet',
+    actions: [
+      {
+        id: 'set_name',
+        description: 'Sets the name of the user to be greeted',
+        params: {
+          name: 'The name of the user',
+        },
+      },
+    ],
+  },
+  // ...
+];
+```
+
+You can use it to present a quick summary of available tools to your model, and then decide on an applet and action to use.
+
+## Feedback & Community
+
+## License
+
+[MIT](./LICENSE.md)
+
+---
+
+Built by [Unternet](https://unternet.co).

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import { AppletAction, AppletHeader, AppletMessage, ActionParams, AppletManifest } from './types';
+export declare function getHeaders(url: string): Promise<AppletHeader[]>;
+export declare function getManifests(url: string): Promise<any[]>;
+export declare function load(url: string, container: HTMLIFrameElement): Promise<Applet>;
+export declare class Applet<T = unknown> extends EventTarget {
+    #private;
+    actions: AppletAction[];
+    manifest: AppletManifest;
+    container: HTMLIFrameElement;
+    constructor();
+    get state(): T;
+    set state(state: T);
+    toJson(): {
+        [k: string]: any;
+    };
+    resizeContainer(dimensions: {
+        height: number;
+        width: number;
+    }): void;
+    onstateupdated(event: CustomEvent): void;
+    disconnect(): void;
+    dispatchAction(actionId: string, params: ActionParams): Promise<AppletMessage<any>>;
+}
+export declare function loadManifest(url: string): Promise<AppletManifest>;

package/dist/client.js

@@ -0,0 +1,151 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Applet_state;
+import { AppletMessage, } from './types';
+const hiddenRoot = document.createElement('div');
+hiddenRoot.style.display = 'none';
+document.body.appendChild(hiddenRoot);
+export async function getHeaders(url) {
+    url = parseUrl(url);
+    try {
+        const request = await fetch(`${url}/manifest.json`);
+        const appManifest = await request.json();
+        const appletHeaders = appManifest.applets;
+        return appletHeaders ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function getManifests(url) {
+    url = parseUrl(url);
+    const request = await fetch(`${url}/manifest.json`);
+    const headers = (await request.json()).applets;
+    const manifests = await Promise.all(headers.map(async (header) => {
+        const appletUrl = parseUrl(header.url);
+        const request = await fetch(`${appletUrl}/manifest.json`);
+        return await request.json();
+    }));
+    return manifests ?? [];
+}
+export async function load(url, container) {
+    url = parseUrl(url);
+    const manifest = await loadManifest(`${url}`);
+    const applet = new Applet();
+    applet.manifest = manifest;
+    applet.actions = manifest.actions; // let the events set this later
+    applet.container = container;
+    container.src = applet.manifest.entrypoint;
+    if (!container.isConnected)
+        hiddenRoot.appendChild(container);
+    return new Promise((resolve) => {
+        window.addEventListener('message', (message) => {
+            if (message.source !== container.contentWindow)
+                return;
+            if (message.data.type === 'ready')
+                resolve(applet);
+        });
+    });
+}
+export class Applet extends EventTarget {
+    constructor() {
+        super();
+        this.actions = [];
+        _Applet_state.set(this, void 0);
+        window.addEventListener('message', (message) => {
+            if (message.source !== this.container.contentWindow)
+                return;
+            if (message.data.type === 'state') {
+                __classPrivateFieldSet(this, _Applet_state, message.data.state, "f");
+                this.dispatchEvent(new CustomEvent('stateupdated', { detail: message.data.detail }));
+                this.onstateupdated(message.data.state);
+            }
+            if (message.data.type === 'resize') {
+                this.resizeContainer(message.data.dimensions);
+            }
+            this.container.contentWindow?.postMessage({
+                type: 'resolve',
+                id: message.data.id,
+            }, '*');
+        });
+    }
+    get state() {
+        return __classPrivateFieldGet(this, _Applet_state, "f");
+    }
+    set state(state) {
+        __classPrivateFieldSet(this, _Applet_state, state, "f");
+        const stateMessage = new AppletMessage('state', { state });
+        this.container.contentWindow?.postMessage(stateMessage.toJson(), '*');
+    }
+    toJson() {
+        return Object.fromEntries(Object.entries(this).filter(([_, value]) => {
+            try {
+                JSON.stringify(value);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }));
+    }
+    resizeContainer(dimensions) {
+        this.container.style.height = `${dimensions.height}px`;
+        // if (!this.#styleOverrides) {
+        //   this.#container.style.height = `${dimensions.height}px`;
+        // }
+    }
+    onstateupdated(event) { }
+    disconnect() { }
+    async dispatchAction(actionId, params) {
+        const requestMessage = new AppletMessage('action', {
+            actionId,
+            params,
+        });
+        this.container.contentWindow?.postMessage(requestMessage.toJson(), '*');
+        return new Promise((resolve) => {
+            const listener = (messageEvent) => {
+                if (messageEvent.source !== this.container.contentWindow)
+                    return;
+                const responseMessage = new AppletMessage(messageEvent.data.type, messageEvent.data);
+                if (responseMessage.type === 'resolve' &&
+                    responseMessage.id === requestMessage.id) {
+                    window.removeEventListener('message', listener);
+                    resolve(responseMessage);
+                }
+            };
+            window.addEventListener('message', listener);
+        });
+    }
+}
+_Applet_state = new WeakMap();
+function parseUrl(url, base) {
+    if (['http', 'https'].includes(url.split('://')[0])) {
+        return url;
+    }
+    let path = url;
+    if (path.startsWith('/'))
+        path = path.slice(1);
+    if (path.endsWith('/'))
+        path = path.slice(0, -1);
+    url = `${base || window.location.origin}/${path}`;
+    return url;
+}
+export async function loadManifest(url) {
+    url = parseUrl(url);
+    const request = await fetch(`${url}/manifest.json`);
+    const appletManifest = await request.json();
+    if (appletManifest.type !== 'applet') {
+        throw new Error("URL doesn't point to a valid applet manifest.");
+    }
+    appletManifest.entrypoint = parseUrl(appletManifest.entrypoint, url);
+    return appletManifest;
+}

package/dist/context.d.ts

@@ -0,0 +1,24 @@
+import { ActionHandlerDict, AppletState, AppletMessage, AppletMessageType, AppletMessageCallback, ActionParams, ActionHandler } from './types';
+/**
+ * Context
+ */
+export declare class AppletContext<StateType = AppletState> extends EventTarget {
+    client: AppletClient;
+    actionHandlers: ActionHandlerDict;
+    state: StateType;
+    connect(): this;
+    setActionHandler<T extends ActionParams>(actionId: string, handler: ActionHandler<T>): void;
+    setState(state: StateType): Promise<void>;
+    onload(): Promise<void> | void;
+    onready(): Promise<void> | void;
+    onrender(): void;
+}
+/**
+ * Client
+ */
+declare class AppletClient {
+    on(messageType: AppletMessageType, callback: AppletMessageCallback): void;
+    send(message: AppletMessage): Promise<void>;
+}
+export declare const appletContext: AppletContext<AppletState>;
+export {};

package/dist/context.js

@@ -0,0 +1,103 @@
+import { AppletMessage, } from './types';
+/**
+ * Context
+ */
+export class AppletContext extends EventTarget {
+    constructor() {
+        super(...arguments);
+        this.actionHandlers = {};
+    }
+    connect() {
+        this.client = new AppletClient();
+        const startup = async () => {
+            await this.onload();
+            this.client.send(new AppletMessage('ready'));
+            this.dispatchEvent(new CustomEvent('ready'));
+            await this.onready();
+        };
+        if (document.readyState === 'complete' ||
+            document.readyState === 'interactive') {
+            setTimeout(startup, 1);
+        }
+        else {
+            window.addEventListener('DOMContentLoaded', startup);
+        }
+        const resizeObserver = new ResizeObserver((entries) => {
+            for (let entry of entries) {
+                const message = new AppletMessage('resize', {
+                    dimensions: {
+                        width: entry.contentRect.width,
+                        height: entry.contentRect.height,
+                    },
+                });
+                this.client.send(message);
+            }
+        });
+        resizeObserver.observe(document.querySelector('html'));
+        this.client.on('state', (message) => {
+            if (!isStateMessage(message)) {
+                throw new TypeError("Message doesn't match type StateMessage");
+            }
+            this.setState(message.state);
+        });
+        this.client.on('action', async (message) => {
+            if (!isActionMessage(message)) {
+                throw new TypeError("Message doesn't match type AppletMessage.");
+            }
+            if (Object.keys(this.actionHandlers).includes(message.actionId)) {
+                await this.actionHandlers[message.actionId](message.params);
+            }
+            message.resolve();
+        });
+        return this;
+    }
+    setActionHandler(actionId, handler) {
+        this.actionHandlers[actionId] = handler;
+    }
+    async setState(state) {
+        const message = new AppletMessage('state', { state });
+        await this.client.send(message);
+        this.state = state;
+        this.dispatchEvent(new CustomEvent('render'));
+        this.onrender(); // TODO: Should come from client? Or stay here, and only activate if mounted? Need a control for mounting.
+    }
+    onload() { }
+    onready() { }
+    onrender() { }
+}
+function isActionMessage(message) {
+    return message.type === 'action';
+}
+function isStateMessage(message) {
+    return message.type === 'state';
+}
+/**
+ * Client
+ */
+class AppletClient {
+    on(messageType, callback) {
+        window.addEventListener('message', (messageEvent) => {
+            if (messageEvent.data.type !== messageType)
+                return;
+            const message = new AppletMessage(messageEvent.data.type, messageEvent.data);
+            message.resolve = () => {
+                window.parent.postMessage(new AppletMessage('resolve', { id: message.id }), '*');
+            };
+            callback(message);
+        });
+    }
+    send(message) {
+        window.parent.postMessage(message.toJson(), '*');
+        return new Promise((resolve) => {
+            const listener = (messageEvent) => {
+                if (messageEvent.data.type === 'resolve' &&
+                    messageEvent.data.id === message.id) {
+                    window.removeEventListener('message', listener);
+                    resolve();
+                }
+            };
+            window.addEventListener('message', listener);
+        });
+    }
+}
+export const appletContext = new AppletContext();

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './utils';
+export * from './types';
+export * as applets from './client';
+export { Applet } from './client';
+export * from './context';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './utils';
+export * from './types';
+import * as applets_1 from './client';
+export { applets_1 as applets };
+export { Applet } from './client';
+export * from './context';

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+export interface AppletManifest {
+    type: 'applet';
+    name: string;
+    description: string;
+    icon?: string;
+    entrypoint: string;
+    actions: AppletAction[];
+}
+export interface AppletAction {
+    id: string;
+    description: string;
+    params?: ActionParamSchema;
+}
+export interface AppletHeader {
+    name: string;
+    description: string;
+    url: string;
+    params: {
+        [key: string]: string;
+    };
+}
+export type AppletState = Record<string, Serializable>;
+export type ActionParamSchema = Record<string, {
+    description: string;
+    type: 'string';
+}>;
+export type ActionParams = Record<string, unknown>;
+export type ActionHandlerDict = {
+    [key: string]: ActionHandler<any>;
+};
+export type ActionHandler<T extends ActionParams> = (params: T) => void | Promise<void>;
+export type AnyAppletMessage = AppletMessage | AppletStateMessage | AppletActionMessage;
+export interface AppletStateMessage<T = any> extends AppletMessage {
+    type: 'state';
+    state: T;
+}
+export interface AppletActionMessage<T = any> extends AppletMessage {
+    type: 'action';
+    actionId: string;
+    params: T;
+}
+export declare class AppletMessage<T = any> {
+    type: AppletMessageType;
+    id: string;
+    timeStamp: number;
+    constructor(type: AppletMessageType, values?: T);
+    toJson(): {
+        [k: string]: any;
+    };
+    resolve(): void;
+}
+export type AppletMessageType = 'action' | 'render' | 'state' | 'ready' | 'resolve' | 'resize';
+export type AppletMessageCallback = (message: AnyAppletMessage) => void;
+type Serializable = string | number | boolean | null | Serializable[] | {
+    [key: string]: Serializable;
+};
+export {};

package/dist/types.js

@@ -0,0 +1,21 @@
+export class AppletMessage {
+    constructor(type, values) {
+        this.timeStamp = Date.now();
+        this.type = type;
+        this.id = crypto.randomUUID();
+        if (values)
+            Object.assign(this, values);
+    }
+    toJson() {
+        return Object.fromEntries(Object.entries(this).filter(([_, value]) => {
+            try {
+                JSON.stringify(value);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }));
+    }
+    resolve() { }
+}

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+import { type AppletManifest } from './types';
+export declare function getAppletsList(url: string): Promise<any>;
+export declare function loadAppletManifest(url: string): Promise<AppletManifest>;

package/dist/utils.js

@@ -0,0 +1,33 @@
+function parseUrl(url, base) {
+    if (['http', 'https'].includes(url.split('://')[0])) {
+        return url;
+    }
+    let path = url;
+    if (path.startsWith('/'))
+        path = path.slice(1);
+    if (path.endsWith('/'))
+        path = path.slice(0, -1);
+    url = `${base || window.location.origin}/${path}`;
+    return url;
+}
+export async function getAppletsList(url) {
+    url = parseUrl(url);
+    try {
+        const request = await fetch(`${url}/manifest.json`);
+        const appManifest = await request.json();
+        return appManifest.applets ? appManifest.applets : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function loadAppletManifest(url) {
+    url = parseUrl(url);
+    const request = await fetch(`${url}/manifest.json`);
+    const appletManifest = await request.json();
+    if (appletManifest.type !== 'applet') {
+        throw new Error("URL doesn't point to a valid applet manifest.");
+    }
+    appletManifest.entrypoint = parseUrl(appletManifest.entrypoint, url);
+    return appletManifest;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@web-applets/sdk",
+  "version": "0.0.4",
+  "description": "The Web Applets SDK, for creating & hosting Web Applets.",
+  "author": "Rupert Manfredi <rupert@unternet.co>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unternet-co/web-applets.git"
+  },
+  "scripts": {
+    "build": "tsc && cp ../README.md ./README.md",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.2"
+  },
+  "dependencies": {
+    "vite": "^5.4.7"
+  }
+}