@moonsurf/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# @moonsurf/sdk
 
-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.
+Run Moonsurf recipes in the person's own browser from your web app, through the Moonsurf
+extension. The person needs only the extension: no desktop app, no sign-in.
+
+How it works (plan `2026-11-09-web-driven-runs`, in `chrome-extension/plans/`):
+
+1. The person trusts your site once: from the Moonsurf button in their toolbar, or when your page
+   calls `requestTrust()` and they accept in the tab the extension opens.
+2. Your page calls `run()` from a click. The extension opens a tab next to yours showing your site,
+   the sites the recipe opens, each step, and what it sends back.
+3. If they choose **Allow and Run**, that same tab runs the steps, then closes, and your tab comes
+   back with the result. They can tick **Always allow this version** so the same recipe runs
+   without asking next time; any change to the recipe asks again.
+
+Chromium browsers only (Chrome, Edge, Brave, …): the extension drives the tab with
+`chrome.debugger`, which Firefox and Safari don't have.
+
+## Use
+
+```ts
+import { moonsurf } from "@moonsurf/sdk";
+
+const recipe = {
+  id: "crm-update-phone",
+  version: 3,
+  name: "Update a contact's phone in the CRM",
+  inputs: {
+    contactId: { type: "string", pattern: "^[0-9]{1,12}$" },
+    phone: { type: "string", maxLength: 40 },
+  },
+  steps: [
+    { open: "https://crm.example.com/contacts/{contactId}" },
+    { check: { selector: "form#contact", notSelector: "#login" } },
+    { fill: { selector: "#phone", value: "{phone}" } },
+    { click: { selector: "button[type=submit]" } },
+    { wait: { selector: ".toast-success" } },
+    { read: { selector: ".updated-at", as: "updatedAt" } },
+  ],
+};
+
+button.onclick = async () => {
+  const status = await moonsurf.status(); // "missing" | "untrusted" | "ready"
+  if (status === "missing") return showInstallLink();
+  if (status === "untrusted") {
+    await moonsurf.requestTrust(); // "trusted" | "denied" | "blocked" | "dismissed"
+    return; // the next click runs: each run needs its own click
+  }
+  const r = await moonsurf.run({
+    requestId: `upd-${contactId}-${Date.now()}`,
+    recipe,
+    inputs: { contactId, phone },
+    onProgress: (p) => show(p), // { state: "awaiting_approval" } then { state: "running", step: 3, of: 6 }
+  });
+  if (r.status === "succeeded") save(r.outputs);
+  else toast(moonsurf.describe(r, "crm.example.com"));
+};
+```
+
+- **Recipes** are Moonsurf's format v1 (`relay/protocol/PROTOCOL.md` section 11): 8 step kinds
+  (`open`, `wait`, `check`, `fill`, `select`, `click`, `press`, `read`), https sites only, at most
+  100 steps and 2 minutes. There are no scripts, cookies, screenshots or downloads.
+- **`run()` and `requestTrust()` need a click or key press** just before (the page's user
+  activation). Without one the answer is `needs_user_gesture`.
+- **`requestId`** is yours: `[A-Za-z0-9_-]{1,128}`, unique for your site. A repeat never runs
+  twice; it gets the first result. `result(requestId)` gets a result back for 24 hours, e.g. after
+  a reload.
+- **One run at a time** per browser; another gets `busy`.
+- A refusal or a failure is a **result**, not an exception. `MoonsurfError` means the extension
+  isn't there or was updated since the page loaded.
+
+## Results
+
+```json
+{ "v": 1, "requestId": "upd-8812-1731122400", "status": "succeeded", "recipeHash": "sha256-…",
+  "outputs": { "updatedAt": "Updated 10:42" }, "startedAt": "…", "finishedAt": "…" }
+{ "v": 1, "requestId": "…", "status": "failed", "recipeHash": "…", "failedStep": 1, "code": "needs_sign_in", "startedAt": "…", "finishedAt": "…" }
+{ "v": 1, "requestId": "…", "status": "refused", "reason": "user_denied", "finishedAt": "…" }
+```
+
+Failure codes: `needs_sign_in`, `check_failed`, `not_found`, `step_timeout`, `job_timeout`,
+`left_allowed_site`, `browser_unavailable`, `tool_error`, `outputs_too_large`, `tab_closed`,
+`detached`. Refusals: `not_trusted`, `needs_user_gesture`, `request_invalid`, `busy`,
+`recipe_invalid`, `host_not_allowed`, `inputs_invalid`, `input_not_allowed`, `user_denied`,
+`prompt_expired`, `unsupported_version`. `describe(result, site)` turns each into a sentence.
+
+## Develop
+
+```sh
+npm install
+npm run build     # dist/
+npm run vendor    # copies src/index.ts into moonsurf-web for its /extension/demo page
+```
+
+`demo/index.html` is a plain page for trying it with a development build of the extension
+(`npm run build:dev` in `chrome-extension`, which also accepts `http://localhost`); the extension's
+`npm run test:e2e` serves it and drives it in Chromium.

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+export type Status = 'missing' | 'untrusted' | 'ready';
+export type TrustResult = 'trusted' | 'denied' | 'blocked' | 'dismissed' | 'needs_user_gesture';
+export type FailureCode = 'needs_sign_in' | 'check_failed' | 'not_found' | 'step_timeout' | 'job_timeout' | 'left_allowed_site' | 'browser_unavailable' | 'tool_error' | 'outputs_too_large' | 'tab_closed' | 'detached';
+export type RefusalReason = 'not_trusted' | 'needs_user_gesture' | 'request_invalid' | 'job_seen' | 'busy' | 'recipe_invalid' | 'host_not_allowed' | 'inputs_invalid' | 'input_not_allowed' | 'user_denied' | 'prompt_expired' | 'unsupported_version';
+export type RunResult = {
+    v: 1;
+    requestId: string;
+    status: 'succeeded';
+    recipeHash: string;
+    outputs: Record<string, string>;
+    startedAt: string;
+    finishedAt: string;
+} | {
+    v: 1;
+    requestId: string;
+    status: 'failed';
+    recipeHash: string;
+    failedStep: number;
+    code: FailureCode | (string & {});
+    startedAt: string;
+    finishedAt: string;
+} | {
+    v: 1;
+    requestId: string;
+    status: 'refused';
+    reason: RefusalReason | (string & {});
+    recipeHash?: string;
+    finishedAt: string;
+};
+export interface Progress {
+    state: 'awaiting_approval' | 'running';
+    /** 1-based step being run, with `of` steps in all (while running). */
+    step?: number;
+    of?: number;
+}
+export interface RunOptions {
+    /** Your own ID for this run, `[A-Za-z0-9_-]{1,128}`, unique for your site. A repeat never runs twice: it gets the first result. */
+    requestId: string;
+    /** A recipe in Moonsurf's format v1. */
+    recipe: unknown;
+    /** The recipe's inputs, all strings. */
+    inputs?: Record<string, string>;
+    onProgress?: (p: Progress) => void;
+}
+/** The extension isn't there, was updated since the page loaded, or gave an answer this SDK doesn't know. */
+export declare class MoonsurfError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/** Whether the extension is installed, and whether it trusts this site. Resolves in at most `timeoutMs`. */
+declare function status(timeoutMs?: number): Promise<Status>;
+/**
+ * Asks the person to trust this site: the extension opens a tab next to this one. Call it from a
+ * click or key handler. Resolves with their answer once they give it.
+ */
+declare function requestTrust(): Promise<TrustResult>;
+/** A run's stored result (kept 24 hours), e.g. after a reload. Null when the extension doesn't know it. */
+declare function result(requestId: string): Promise<RunResult | null>;
+/**
+ * Runs a recipe. Call it from a click or key handler: the extension shows its approval tab (unless
+ * the person always allows this version), runs the steps in that tab, closes it and resolves with
+ * the result. A refusal or a failure is a result, not an exception.
+ */
+declare function run(opts: RunOptions): Promise<RunResult>;
+/** A sentence for the person about a result. `{site}` becomes the recipe's site when you pass it. */
+declare function describe(r: RunResult, site?: string): string;
+export declare const moonsurf: {
+    status: typeof status;
+    requestTrust: typeof requestTrust;
+    run: typeof run;
+    result: typeof result;
+    describe: typeof describe;
+};
+export default moonsurf;

package/dist/index.js

@@ -0,0 +1,175 @@
+// @moonsurf/sdk: lets a web page run recipes in the person's browser through the Moonsurf
+// extension (plan 2026-11-09-web-driven-runs). No dependencies; talks to the extension's bridge
+// content script with window.postMessage.
+//
+//   const s = await moonsurf.status();            // 'missing' | 'untrusted' | 'ready'
+//   await moonsurf.requestTrust();                // from a click: opens the extension's trust tab
+//   const r = await moonsurf.run({ requestId, recipe, inputs, onProgress });   // from a click
+//   moonsurf.describe(r)                          // a sentence for the person
+/** The extension isn't there, was updated since the page loaded, or gave an answer this SDK doesn't know. */
+export class MoonsurfError extends Error {
+    constructor(code) {
+        super(`moonsurf: ${code}`);
+        this.code = code;
+        this.name = 'MoonsurfError';
+    }
+}
+const pending = new Map();
+const listeners = new Set();
+let counter = 0;
+let listening = false;
+function listen() {
+    if (listening || typeof window === 'undefined')
+        return;
+    listening = true;
+    window.addEventListener('message', (event) => {
+        if (event.source !== window || event.origin !== location.origin)
+            return;
+        const d = event.data;
+        if (d?.moonsurf !== 1 || d.dir !== 'ext')
+            return;
+        if (typeof d.re === 'string') {
+            const done = pending.get(d.re);
+            if (done) {
+                pending.delete(d.re);
+                done((d.reply ?? {}));
+            }
+            return;
+        }
+        if (d.event && typeof d.event === 'object')
+            for (const l of [...listeners])
+                l(d.event);
+    });
+}
+/** Sends one message to the bridge; resolves with its reply, or null after `timeoutMs`. */
+function send(type, fields = {}, timeoutMs) {
+    listen();
+    const id = `m${Date.now().toString(36)}${(counter++).toString(36)}`;
+    return new Promise((resolve) => {
+        let timer;
+        pending.set(id, (reply) => {
+            clearTimeout(timer);
+            resolve(reply);
+        });
+        if (timeoutMs !== undefined) {
+            timer = setTimeout(() => {
+                pending.delete(id);
+                resolve(null);
+            }, timeoutMs);
+        }
+        window.postMessage({ moonsurf: 1, dir: 'page', id, type, ...fields }, location.origin);
+    });
+}
+function check(reply) {
+    if (reply === null)
+        throw new MoonsurfError('extension_missing');
+    if (typeof reply.error === 'string')
+        throw new MoonsurfError(reply.error);
+    return reply;
+}
+/** Whether the extension is installed, and whether it trusts this site. Resolves in at most `timeoutMs`. */
+async function status(timeoutMs = 300) {
+    const r = await send('hello', {}, timeoutMs);
+    if (r === null || typeof r.error === 'string')
+        return 'missing';
+    return r.trusted === true ? 'ready' : 'untrusted';
+}
+/**
+ * Asks the person to trust this site: the extension opens a tab next to this one. Call it from a
+ * click or key handler. Resolves with their answer once they give it.
+ */
+async function requestTrust() {
+    listen();
+    let decided;
+    const decision = new Promise((resolve) => (decided = resolve));
+    const onEvent = (e) => {
+        if (e.kind === 'trust' && e.origin === location.origin)
+            decided(e.status);
+    };
+    listeners.add(onEvent);
+    try {
+        const r = check(await send('requestTrust'));
+        if (r.status === 'pending')
+            return await decision;
+        return r.status;
+    }
+    finally {
+        listeners.delete(onEvent);
+    }
+}
+/** A run's stored result (kept 24 hours), e.g. after a reload. Null when the extension doesn't know it. */
+async function result(requestId) {
+    const r = check(await send('result', { requestId }, 5000));
+    return r.result ?? null;
+}
+/**
+ * Runs a recipe. Call it from a click or key handler: the extension shows its approval tab (unless
+ * the person always allows this version), runs the steps in that tab, closes it and resolves with
+ * the result. A refusal or a failure is a result, not an exception.
+ */
+async function run(opts) {
+    listen();
+    let finish;
+    const finished = new Promise((resolve) => (finish = resolve));
+    const onEvent = (e) => {
+        if (e.kind !== 'run' || e.requestId !== opts.requestId)
+            return;
+        if (e.event === 'result')
+            finish(e.result);
+        else
+            opts.onProgress?.({ state: e.state, ...(e.step !== undefined ? { step: e.step, of: e.of } : {}) });
+    };
+    listeners.add(onEvent);
+    let poll;
+    try {
+        const r = check(await send('run', { requestId: opts.requestId, recipe: opts.recipe, inputs: opts.inputs ?? {} }));
+        if (r.result)
+            return r.result;
+        if (!r.accepted && !r.inProgress)
+            throw new MoonsurfError('unexpected_reply');
+        if (r.accepted)
+            opts.onProgress?.({ state: r.state === 'running' ? 'running' : 'awaiting_approval' });
+        // The result comes as an event; asking now and then covers a missed one.
+        poll = setInterval(() => {
+            void result(opts.requestId).then((x) => x && finish(x), () => { });
+        }, 3000);
+        return await finished;
+    }
+    finally {
+        clearInterval(poll);
+        listeners.delete(onEvent);
+    }
+}
+const SENTENCES = {
+    succeeded: 'Done.',
+    needs_sign_in: 'Sign in to {site}, then try again.',
+    check_failed: '{site} didn’t show the page the automation expected.',
+    not_found: 'Something the automation needed wasn’t on the page at {site}.',
+    step_timeout: '{site} took too long to respond.',
+    job_timeout: 'The automation took longer than 2 minutes and was stopped.',
+    left_allowed_site: 'The page went to a site the automation isn’t allowed to use, so it stopped.',
+    browser_unavailable: 'The browser tab went away before the automation finished.',
+    tool_error: 'The browser couldn’t do one of the steps.',
+    outputs_too_large: 'The automation read more than it may send back.',
+    tab_closed: 'The tab was closed before the automation finished.',
+    detached: 'The automation was stopped from Chrome’s debugging bar.',
+    not_trusted: 'Moonsurf doesn’t trust this site yet.',
+    needs_user_gesture: 'Start the automation with a click.',
+    busy: 'Another automation is running in this browser. Try again when it ends.',
+    user_denied: 'The automation wasn’t allowed.',
+    prompt_expired: 'The request waited 5 minutes without an answer.',
+    recipe_invalid: 'This automation isn’t valid.',
+    host_not_allowed: 'This automation uses a site Moonsurf doesn’t allow.',
+    inputs_invalid: 'Some of the values given to the automation aren’t valid.',
+    input_not_allowed: 'Some of the values given to the automation aren’t valid.',
+    request_invalid: 'The request ID isn’t valid.',
+    job_seen: 'This request already ran.',
+    unsupported_version: 'This version of the extension can’t run this request.',
+};
+/** A sentence for the person about a result. `{site}` becomes the recipe's site when you pass it. */
+function describe(r, site = 'the site') {
+    const key = r.status === 'succeeded' ? 'succeeded' : r.status === 'failed' ? r.code : r.reason;
+    return (SENTENCES[key] ?? 'The automation didn’t finish.').replace('{site}', site);
+}
+export const moonsurf = { status, requestTrust, run, result, describe };
+export default moonsurf;

package/package.json

@@ -1,6 +1,27 @@
 {
-  "name": "@moonsurf/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@moonsurf/sdk",
+    "version": "0.1.0",
+    "description": "Run Moonsurf recipes in the person's browser from your web app, through the Moonsurf extension, with their approval.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "sideEffects": false,
+    "license": "UNLICENSED",
+    "homepage": "https://moonsurf.ai",
+    "scripts": {
+        "build": "tsc -p .",
+        "vendor": "node scripts/vendor.mjs"
+    },
+    "devDependencies": {
+        "typescript": "5.7.3"
+    }
+}