@web-applets/sdk 0.0.6 → 0.0.7

package/README.md

@@ -2,6 +2,8 @@
 
 > An open SDK to create interoperable actions & views for agents – _a web of capabilities!_
 
+🔗 [Community Applets Repo](https://github.com/unternet-co/community-applets)
+
 ## 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.
@@ -10,15 +12,27 @@ Did we mention it's _interoperable_? We think the future of software should be o
 
 ## 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`.
+Install the applets SDK & CLI:
+
+```bash
+npm i --save @web-applets/sdk
+npm i --save-dev @web-applets/cli
+```
+
+Then, initialize the `applets.config.json` and create a new blank applet:
+
+```bash
+npx applets init
+npx applets create <your-applet-name>
+```
 
-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.
+This creates an applet folder, with a build system built-in using Vite. You can change this to anything you want. We recommend building at this stage, as the SDK currently needs to be bundled. We're working on adding a statically hosted script to import.
 
 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
+- `src/main.ts`: 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.
 
@@ -42,7 +56,7 @@ Let's say we want our applet to respond to a "set_name" action and render the us
 }
 ```
 
-Now let's update `main.ts` to assign an action handler:
+Now let's update `src/main.ts` to assign an action handler:
 
 ```js
 // First, import the SDK
@@ -69,44 +83,42 @@ applet.onrender = () => {
 };
 ```
 
-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.
+Now if you run `npx applets playground`, 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:
+Using Web Applets is just as easy as creating them!
+
+First, build your applets. By default, this goes into a folder called `dist/`, but you'll likely want to change this in `applets.config.json` to point to wherever you're serving public files from. For example, in a Vite project, edit this to be `./public`.
+
+Then, run:
 
 ```bash
-npm install @unternet/web-applets
+npx applets build
 ```
 
-In your code, you can import the applets client:
+Now in your main app, you can import the applets client:
 
 ```js
-import { applets } from '@unternet/web-applets';
+import { applets } from '@web-applets/sdk';
 ```
 
-Now you can create a new applet from a URL:
+Now you can import your applets from wherever they're being served from (note – you can also host them anywhere on the web):
 
 ```js
-const applet = await applets.load(
-  `https://unternet.co/applets/helloworld.applet`
-);
+const applet = await applets.load('/helloworld.applet'); // replace with a URL if hosted remotely
 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:
+The above applet is actually running headless, but we can get it to display by attaching it to a container. 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
-);
+const applet = await applets.load(`/helloworld.applet`, container);
 ```
 
 To load pre-existing saved state into an applet, simply set the state property:
@@ -116,7 +128,7 @@ 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.
+It may also be helpful to check available applets at a domain, or in your public folder. 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('/');
@@ -148,6 +160,10 @@ You can use it to present a quick summary of available tools to your model, and
 
 ## Feedback & Community
 
+This is a community project, and we're open to community members discussing the project direction, and submitting code!
+
+To join the conversation, visit the Applets mailing list at [groups.google.com/a/unternet.co/g/community](https://groups.google.com/a/unternet.co/g/community). You can also find more about the company that's kicking off this work at [unternet.co](https://unternet.co)
+
 ## License
 
 [MIT](./LICENSE.md)

package/dist/context.d.ts

@@ -1,8 +1,8 @@
-import { ActionHandlerDict, AppletState, AppletMessage, AppletMessageType, AppletMessageCallback, ActionParams, ActionHandler } from './types';
+import { ActionHandlerDict, AppletMessage, AppletMessageType, AppletMessageCallback, ActionParams, ActionHandler } from './types';
 /**
  * Context
  */
-export declare class AppletContext<StateType = AppletState> extends EventTarget {
+export declare class AppletContext<StateType = any> extends EventTarget {
     client: AppletClient;
     actionHandlers: ActionHandlerDict;
     state: StateType;
@@ -20,5 +20,5 @@ declare class AppletClient {
     on(messageType: AppletMessageType, callback: AppletMessageCallback): void;
     send(message: AppletMessage): Promise<void>;
 }
-export declare const appletContext: AppletContext<AppletState>;
+export declare const appletContext: AppletContext<any>;
 export {};

package/dist/utils.d.ts

@@ -1,3 +1,18 @@
-import { type AppletManifest } from './types';
+import { AppletAction, type AppletManifest } from './types';
 export declare function getAppletsList(url: string): Promise<any>;
 export declare function loadAppletManifest(url: string): Promise<AppletManifest>;
+export declare function createOpenAISchemaForAction(action: AppletAction): {
+    strict: boolean;
+    name: string;
+    schema: {
+        type: string;
+        required: string[];
+        properties: {
+            id: {
+                type: string;
+            };
+            params: import("./types").ActionParamSchema;
+        };
+        additionalProperties: boolean;
+    };
+};

package/dist/utils.js

@@ -31,3 +31,18 @@ export async function loadAppletManifest(url) {
     appletManifest.entrypoint = parseUrl(appletManifest.entrypoint, url);
     return appletManifest;
 }
+export function createOpenAISchemaForAction(action) {
+    return {
+        strict: true,
+        name: 'action_schema',
+        schema: {
+            type: 'object',
+            required: Object.keys(action),
+            properties: {
+                id: { type: 'string' },
+                params: action.params,
+            },
+            additionalProperties: false,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-applets/sdk",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "The Web Applets SDK, for creating & hosting Web Applets.",
   "author": "Rupert Manfredi <rupert@unternet.co>",
   "license": "MIT",