@engenty/wizards-runtime 0.7.11 → 0.8.0

package/README.md

@@ -21,6 +21,9 @@
 - **Share it with a link.** Anyone can run a wizard in the browser, on a phone too: camera,
   code scan, voice notes, location and a drawn signature included. Results download as PDF,
   Word, HTML, Markdown, PNG, MP4, MP3, CSV, Excel or JSON, or go out as a link.
+- **Send the result on.** From the result, by email, into Google Drive, OneDrive or S3, to a
+  Slack channel, through any connected service, or onto a website the wizard opens in its
+  browser – you sign in yourself and confirm before anything goes public.
 - **Runs on your machine, on your subscription.** It uses Codex, Claude Code, Antigravity
   or Cursor Agent when one is installed and signed in, so no API key is needed. Or bring a key
   (Vercel AI Gateway, OpenAI, Anthropic), or a local model through Ollama. Your wizards and
@@ -130,7 +133,8 @@ Change it later under Settings → Models.
 - **Make a wizard:** describe it in the studio’s chat, or start from one of the templates.
   You see the steps as a diagram and can change any of them.
 - **Run and share:** try it yourself, then share the link. Shared results are kept for 7 days
-  for people without an account.
+  for people without an account. “Teilen” on a result also sends it by email, saves it to a
+  cloud folder or posts it: [Sharing a result](docs/development.md#sharing-a-result).
 - **Connect services:** Gmail, Google Drive, Calendar, Contacts, Outlook, OneDrive, Slack,
   GitHub, HubSpot and S3 are built in; any other service can be added from its API description
   or MCP server through the [integrations.sh](https://integrations.sh) registry. Services that

package/apps/runtime/dist/authoring/guide.js

@@ -282,7 +282,8 @@ type ReviewStep = { type: "review", show: (stepId | "lists.<listId>")[], edit?:
 // shows earlier outputs; the person accepts, edits text outputs (edit), or asks for a new version with a note (regenerate)
 // a shown list is edited in place by the person
 
-type ResultStep = { type: "result", message?: string, deliverables: { from: stepId | "lists.<listId>", label?, formats: Format[] }[] }
+type ResultStep = { type: "result", message?: string, deliverables: { from: stepId | "lists.<listId>", label?, formats: Format[] }[],
+                    share?: { target: string, label?: string, values?: { [fieldId]: string } }[] }
 // formats per source: image→png · video→mp4 (several results: zip) · voice→mp3 · document→pdf docx html md png · dashboard→html pdf png
 //                     film widget (video: true)→mp4 png · film→mp4
 //                     widget→html png pdf mp4 json (mp4 only when the widget registers a timeline)
@@ -290,6 +291,16 @@ type ResultStep = { type: "result", message?: string, deliverables: { from: step
 //                     agent json with schema→json csv xlsx md pdf
 //                     agent, any format→zip: the FILES the step kept with mail_save / browser_download
 //                     lists.<id>→xlsx csv json md · zip (a list with check.file: the kept files its rows name, plus the list)
+// share: where the person can send or publish the result with one button, besides the link and the downloads. They pick the
+//   target, connect their account once, check the prefilled form and send. Targets and the fields "values" can prefill:
+//     "email" (to, subject, message — the picked files go as attachments) · "slack" (channel, message)
+//     "storage:google-drive" | "storage:microsoft-onedrive" | "storage:s3" (folder)
+//     "connector:<connectorId>" (instructions — an agent does it with the connector's actions and asks the person before every change)
+//     "browser" (url, instructions — an agent posts it on any website in the wizard's browser; the person signs in themselves and confirms before it goes public)
+//   Left out: every target that needs no model. []: none. A list: exactly these, in this order — "browser" and "connector:…" then run
+//   for END USERS too, on the admin's credits. "label" names the button ("Auf LinkedIn posten"); values take {{templates}}:
+//   { target: "email", label: "An mich senden", values: { to: "{{email}}", subject: "Dein Angebot von {{brand.name}}" } }
+//   { target: "browser", label: "Auf LinkedIn posten", values: { url: "https://www.linkedin.com/feed/", instructions: "Erstelle einen Beitrag mit dem Text und dem Bild." } }
 
 Templates (in instructions/prompt): {{fieldId}} · {{steps.stepId}} (whole output) · {{steps.stepId.key}} (json key)
   · {{itemsField}} (line items as a table WITH computed net/VAT/total) · {{itemsField.net|vat|gross}} · {{today}}
@@ -317,7 +328,8 @@ How good wizards look:
 - Money/totals: use an "items" field with vat — the runner computes totals; documents must use {{items}} verbatim. Never let a model compute totals.
 - Facts from the web need an agent step with web_search + web_fetch BEFORE writing; documents then cite those notes.
 - Live data with a free public JSON API (weather and wind: api.open-meteo.com; sunrise/sunset is in it too) → an agent step with the http tool and model "standard" that calls the API and returns json. Far cheaper and more exact than web research; use web research only when no API exists.
-- Writing into other systems (CRM, database, spreadsheet, website): an agent step with the matching mcp server, http, or browser tool, preceded by a review step.
+- Writing into other systems (CRM, database, spreadsheet, website): an agent step with the matching mcp server, http, or browser tool, preceded by a review step. Such a step hands over an earlier step's output as a file by naming it "result:<stepId>.<format>" — to browser_upload, or as "file:result:<stepId>.<format>" where a connector action takes "*_base64".
+- Sending the finished result on (mail it, file it in a cloud folder, post it on social media or a website, put it into an ads account): do not build a step for it. Put the targets into the result step's "share": the person sees the result first and sends it with one button. Build an agent step only when the wizard must write somewhere without being asked.
 ${sandboxGuideLine()}
 - Remembering between runs ("merke dir", "führe eine Liste"): declare a list and let an agent step save into it with list_write; a later run reads it as {{lists.id}} or list_read. Give it a key column so known rows are updated, not duplicated. Never make the person re-upload last time's result.
 - Collecting from everyone who runs the wizard (requests, leads, sign-ups, feedback): a list with "shared": true, saved with list_write. It is the admin's, under Space → Data; never show one person's rows to another. Longer text for every run (a running summary, a log): the "pages" tool.

package/apps/runtime/dist/cli/exec.js

@@ -47,7 +47,8 @@ export function runLogged(command, args, options = {}) {
 }
 /**
  * Runs a file and gives what it printed, like execFile: it rejects when the file is not there,
- * ends with another code than 0, or takes longer than `timeout`.
+ * ends with another code than 0, or takes longer than `timeout` (then with `killed` and `signal`
+ * set, as execFile does).
  */
 export function runFile(file, args, options = {}) {
     return new Promise((resolve, reject) => {
@@ -73,6 +74,8 @@ export function runFile(file, args, options = {}) {
             else {
                 reject(Object.assign(new Error(`${file} ended with ${signal ?? code}`), {
                     code,
+                    signal,
+                    killed: child.killed,
                     stdout,
                     stderr,
                 }));

package/apps/runtime/dist/connectors/builtin.js

@@ -13,11 +13,12 @@ import { managed } from "../manage.js";
 import { gmailConnector as mailGmail } from "./gmail.js";
 import { imapConnector } from "./imap.js";
 import { outlookConnector as mailOutlook } from "./outlook.js";
+import { smtpConnector } from "./smtp.js";
 import { googleThroughAccount } from "./via-account.js";
 /**
  * engenty's own connectors, as engenty ships them: Gmail, Drive, Calendar, Contacts, Outlook,
- * OneDrive, Slack, GitHub, HubSpot, S3. Every project has them; an OAuth one can be connected
- * once its client is configured.
+ * OneDrive, Slack, GitHub, HubSpot, S3 — and SMTP, for sending from any mailbox. Every project
+ * has them; an OAuth one can be connected once its client is configured.
  */
 export const BUILTIN_CONNECTORS = [
     ...googleConnectors,
@@ -27,6 +28,7 @@ export const BUILTIN_CONNECTORS = [
     githubConnector,
     hubspotConnector,
     s3Connector,
+    smtpConnector,
 ];
 /** The connectors behind a connection of kind "mail": one read-only shape for any mailbox. */
 export const MAIL_CONNECTORS = [mailGmail, mailOutlook, imapConnector];

package/apps/runtime/dist/connectors/index.js

@@ -14,7 +14,7 @@ import { resolveConnector } from "./external.js";
 import { AccountConnectError, redeemTicket, refreshThroughAccount, startThroughAccount, } from "./via-account.js";
 /** The connectors a person can pick for each kind of connection. */
 const CONNECTORS = { mail: MAIL_CONNECTORS };
-const HINTS = { imap: "imapHint" };
+const HINTS = { imap: "imapHint", smtp: "imapHint" };
 /** The built-in connectors' fields in each language; their definitions say them in English. */
 const FIELD_WORDS = {
     de: {
@@ -23,6 +23,11 @@ const FIELD_WORDS = {
             password: { label: "Passwort oder App-Passwort" },
             host: { label: "IMAP-Server", placeholder: "leer lassen bei Gmail, GMX, iCloud …" },
         },
+        smtp: {
+            email: { label: "E-Mail-Adresse", placeholder: "name@firma.at" },
+            password: { label: "Passwort oder App-Passwort" },
+            host: { label: "SMTP-Server", placeholder: "leer lassen bei Gmail, GMX, iCloud …" },
+        },
     },
 };
 /**
@@ -30,7 +35,8 @@ const FIELD_WORDS = {
  * may use needs. A wizard that only reads never asks for the right to send or delete.
  */
 function scopesFor(connection, connector) {
-    const scopes = new Set(scopesForGroups(connector, new Set(["read"])));
+    // A share target's connection asks for what its actions need and nothing to read with.
+    const scopes = new Set(scopesForGroups(connector, new Set(connection.target ? [] : ["read"])));
     for (const action of connector.actions) {
         if (connection.actions?.includes(action.id)) {
             for (const scope of action.providerScopes ?? []) {
@@ -40,6 +46,24 @@ function scopesFor(connection, connector) {
     }
     return [...scopes];
 }
+const sources = [];
+export function registerConnectionSource(source) {
+    sources.push(source);
+}
+/** A connection of a run by id: one the wizard declares, or one of a share target. */
+export async function findConnection(run, connectionId, projectId) {
+    const declared = run.definition.connections?.find((c) => c.id === connectionId);
+    if (declared) {
+        return declared;
+    }
+    for (const source of sources) {
+        const found = await source(run, connectionId, projectId);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
 /** Where the provider sends the person back; must be registered with the OAuth client. */
 export function connectRedirectUri() {
     return env.connectRedirectUrl || `${env.appUrl}/api/connect/callback`;
@@ -47,8 +71,15 @@ export function connectRedirectUri() {
 const slot = (connectionId) => `connection:${connectionId}`;
 /** A connector that needs no credential: there is nothing for the person to connect. */
 const open = (connector) => connector.auth.kind === "api_key" && connector.auth.apiKey.fields.length === 0;
-/** The connectors behind a connection: the built-in ones of its kind, or the one it names. */
+/**
+ * The connectors behind a connection: the built-in ones of its kind, the one it names, or the
+ * ones a share target lets the person pick from.
+ */
 async function candidates(connection, projectId) {
+    if (connection.target) {
+        const found = await Promise.all(connection.target.connectors.map((id) => resolveConnector(projectId, id)));
+        return found.flatMap((f) => (f ? [f.connector] : []));
+    }
     if (connection.connector) {
         const found = await resolveConnector(projectId, connection.connector);
         return found ? [found.connector] : [];
@@ -173,7 +204,7 @@ export async function finishOAuth(answer, rawState) {
         throw new Error("The sign-in has expired. Connect again.");
     }
     const run = await db.query.run.findFirst({ where: eq(schema.run.id, state.runId) });
-    const connection = run?.definition.connections?.find((c) => c.id === state.connectionId);
+    const connection = run ? await findConnection(run, state.connectionId, state.projectId) : null;
     if (!connection) {
         throw new Error("The run this sign-in belongs to is gone.");
     }

package/apps/runtime/dist/connectors/smtp.js

@@ -0,0 +1,221 @@
+import nodemailer from "nodemailer";
+import MailComposer from "nodemailer/lib/mail-composer/index.js";
+import { z } from "zod";
+import { env } from "../env.js";
+import { assertPublicUrl } from "../tools/net-guard.js";
+const KNOWN_HOSTS = {
+    "gmail.com": "smtp.gmail.com",
+    "googlemail.com": "smtp.gmail.com",
+    "outlook.com": "smtp-mail.outlook.com",
+    "hotmail.com": "smtp-mail.outlook.com",
+    "live.com": "smtp-mail.outlook.com",
+    "icloud.com": "smtp.mail.me.com",
+    "me.com": "smtp.mail.me.com",
+    "yahoo.com": "smtp.mail.yahoo.com",
+    "gmx.at": "mail.gmx.net",
+    "gmx.de": "mail.gmx.net",
+    "gmx.net": "mail.gmx.net",
+    "web.de": "smtp.web.de",
+    "a1.net": "securemail.a1.net",
+    "fastmail.com": "smtp.fastmail.com",
+};
+const ALLOW_PRIVATE = process.env.ALLOW_PRIVATE_FETCH === "1";
+async function transportOf(credentials) {
+    const email = credentials.email.trim();
+    const domain = email.split("@")[1]?.toLowerCase() ?? "";
+    const host = credentials.host?.trim() || KNOWN_HOSTS[domain] || `smtp.${domain}`;
+    const port = Number(credentials.port) || 587;
+    if (!ALLOW_PRIVATE && port !== 587 && port !== 465) {
+        throw new Error("SMTP runs on port 587 (or 465).");
+    }
+    // The host is typed by the person: it must be a public mail server, never this server's network.
+    if (!ALLOW_PRIVATE) {
+        await assertPublicUrl(`https://${host}`);
+    }
+    return nodemailer.createTransport({
+        host,
+        port,
+        secure: port === 465,
+        auth: { user: email, pass: credentials.password },
+        connectionTimeout: 20_000,
+        socketTimeout: 60_000,
+        ...(ALLOW_PRIVATE ? { tls: { rejectUnauthorized: false } } : {}),
+    });
+}
+/** A failed sign-in reads the same whichever mail library met it. */
+function asConnectError(err) {
+    const e = err;
+    if (e?.code === "EAUTH" || e?.responseCode === 535) {
+        return Object.assign(new Error("authentication failed"), { authenticationFailed: true });
+    }
+    if (e?.code === "EDNS" || e?.code === "ESOCKET" || e?.code === "ECONNECTION") {
+        return Object.assign(new Error("server not reachable"), { code: "ENOTFOUND" });
+    }
+    return err;
+}
+const address = (list) => list.map((a) => a.trim()).filter(Boolean);
+function mailOptions(message, from) {
+    return {
+        ...(from ? { from } : {}),
+        to: address(message.to),
+        cc: address(message.cc ?? []),
+        subject: message.subject,
+        text: message.text,
+        attachments: (message.attachments ?? []).map((a) => ({
+            filename: a.name,
+            contentType: a.mime,
+            content: Buffer.from(a.data),
+        })),
+    };
+}
+/** The message as RFC 822 bytes, for providers that take a finished mail (Gmail, Outlook). */
+export function mimeOf(message) {
+    return new MailComposer(mailOptions(message)).compile().build();
+}
+async function sendSmtp(credentials, message) {
+    const transport = await transportOf(credentials);
+    try {
+        await transport.sendMail(mailOptions(message, credentials.email.trim()));
+    }
+    finally {
+        transport.close();
+    }
+}
+// --- the server's own address -------------------------------------------------
+/** The address the server sends from when `SMTP_URL` is set, else null. */
+export function serverSender() {
+    return env.mail.smtpUrl ? env.mail.from || null : null;
+}
+/** Sends from the server's own address: nobody has to connect a mailbox. */
+export async function sendFromServer(message) {
+    const from = serverSender();
+    if (!from) {
+        throw new Error("This server has no address to send from.");
+    }
+    const transport = nodemailer.createTransport(env.mail.smtpUrl);
+    try {
+        await transport.sendMail(mailOptions(message, from));
+    }
+    finally {
+        transport.close();
+    }
+}
+// --- the person's own account --------------------------------------------------
+/** Graph takes a finished mail only up to its request limit of 4 MB (base64 of the bytes). */
+const OUTLOOK_MIME_LIMIT = 2_900_000;
+/** The connectors a mail can be sent with, as the person's own account. */
+export const MAIL_SENDERS = ["smtp", "google-gmail", "microsoft-outlook"];
+/** Sends as the connected account, whichever connector it was connected with. */
+export async function sendAsAccount(connector, ctx, message) {
+    if (connector.id === "smtp") {
+        await sendSmtp(JSON.parse(ctx.accessToken), message);
+        return;
+    }
+    const mime = await mimeOf(message);
+    if (connector.id === "google-gmail") {
+        const res = await ctx.fetchImpl("https://gmail.googleapis.com/upload/gmail/v1/users/me/messages/send?uploadType=media", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${ctx.accessToken}`, "Content-Type": "message/rfc822" },
+            body: new Uint8Array(mime),
+        });
+        if (!res.ok) {
+            throw new Error(`Gmail (${res.status}): ${(await res.text()).slice(0, 200)}`);
+        }
+        return;
+    }
+    if (connector.id === "microsoft-outlook") {
+        if (mime.byteLength > OUTLOOK_MIME_LIMIT) {
+            throw new MailTooLarge();
+        }
+        const res = await ctx.fetchImpl("https://graph.microsoft.com/v1.0/me/sendMail", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${ctx.accessToken}`, "Content-Type": "text/plain" },
+            body: mime.toString("base64"),
+        });
+        if (!res.ok) {
+            throw new Error(`Outlook (${res.status}): ${(await res.text()).slice(0, 200)}`);
+        }
+        return;
+    }
+    throw new Error(`${connector.name} cannot send mail.`);
+}
+/** The attachments are more than the account's provider takes in one mail. */
+export class MailTooLarge extends Error {
+}
+// --- the connector ----------------------------------------------------------------
+const sendInput = z.object({
+    to: z.array(z.string().min(3)).min(1).max(20).describe("Recipient addresses."),
+    cc: z.array(z.string().min(3)).max(20).optional(),
+    subject: z.string().describe("Subject line."),
+    body_text: z.string().describe("Plain-text body."),
+    attachment_base64: z
+        .string()
+        .optional()
+        .describe("One attachment: `file:<path>` of a kept file or `upload:<id>`."),
+    attachment_name: z.string().optional().describe("File name of the attachment."),
+});
+export const smtpConnector = {
+    id: "smtp",
+    moduleId: "wizards-mail",
+    name: "E-Mail (SMTP)",
+    description: "Send mail from any mailbox over SMTP (GMX, iCloud, your own domain …).",
+    icon: "mail",
+    toolPrefix: "smtp",
+    auth: {
+        kind: "api_key",
+        apiKey: {
+            fields: [
+                { key: "email", label: "Email address", placeholder: "name@company.com" },
+                { key: "password", label: "Password or app password", secret: true },
+                {
+                    key: "host",
+                    label: "SMTP server",
+                    placeholder: "leave empty for Gmail, GMX, iCloud …",
+                    required: false,
+                },
+                { key: "port", label: "Port", placeholder: "587", required: false },
+            ],
+            verify: async (credentials) => {
+                const transport = await transportOf(credentials);
+                try {
+                    await transport.verify();
+                }
+                catch (err) {
+                    throw asConnectError(err);
+                }
+                finally {
+                    transport.close();
+                }
+                return { label: credentials.email.trim(), externalId: credentials.email.trim() };
+            },
+        },
+    },
+    actions: [
+        {
+            id: "send_message",
+            summary: "Send an e-mail",
+            description: "Send an e-mail from the connected mailbox right away (plain text, one optional attachment). Irreversible.",
+            group: "destructive",
+            inputSchema: sendInput,
+            handler: async (raw, ctx) => {
+                const input = sendInput.parse(raw);
+                await sendSmtp(JSON.parse(ctx.accessToken), {
+                    to: input.to,
+                    cc: input.cc,
+                    subject: input.subject,
+                    text: input.body_text,
+                    attachments: input.attachment_base64
+                        ? [
+                            {
+                                name: input.attachment_name || "attachment",
+                                mime: "application/octet-stream",
+                                data: Buffer.from(input.attachment_base64, "base64"),
+                            },
+                        ]
+                        : [],
+                });
+                return { sent: true, to: input.to, subject: input.subject };
+            },
+        },
+    ],
+};

package/apps/runtime/dist/db/migrations/tenant/0018_share_job.sql

@@ -0,0 +1,18 @@
+CREATE TABLE `share_job` (
+	`id` text PRIMARY KEY NOT NULL,
+	`run_id` text NOT NULL,
+	`tenant_id` text NOT NULL,
+	`target` text NOT NULL,
+	`name` text NOT NULL,
+	`icon` text NOT NULL,
+	`status` text NOT NULL,
+	`request` text NOT NULL,
+	`events` text DEFAULT '[]' NOT NULL,
+	`result` text,
+	`error` text,
+	`created_at` integer DEFAULT (unixepoch() * 1000) NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch() * 1000) NOT NULL,
+	FOREIGN KEY (`run_id`) REFERENCES `run`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `share_job_run` ON `share_job` (`run_id`,`created_at`);