@visualautomate/plugin-sdk 0.6.1 → 0.8.0

package/dist/runtime.d.ts

@@ -0,0 +1,42 @@
+/** The console a step has: these four methods, and no others. */
+export interface PluginConsole {
+    log(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+}
+export interface LoadOptions {
+    /**
+     * The `fetch` the step gets. Pass a guarded one to apply an egress rule;
+     * without it, this process's own.
+     */
+    fetch?: typeof fetch;
+    /** Where the step's console output goes. Defaults to this process's console. */
+    console?: Partial<PluginConsole>;
+    /** How long the code's top level may take to run, in milliseconds. */
+    timeoutMs?: number;
+}
+/** A console with exactly the platform's four methods, writing where `target` says. */
+export declare function pluginConsole(target?: Partial<PluginConsole>): PluginConsole;
+/**
+ * The globals a step's context starts with: the platform's list, taken from
+ * this process where the platform takes them from its own, and the blocked
+ * names set to undefined.
+ */
+export declare function sandboxGlobals(options?: LoadOptions): Record<string, unknown>;
+/**
+ * Evaluate a step's code as the runner does, and return what it exported.
+ *
+ * The code is wrapped exactly as the runner wraps it, on one line with nothing
+ * added after it, so a file the platform cannot load fails to load here too:
+ * a last line that is a `//` comment with no newline after it comments out the
+ * wrapper's closing bracket on the platform, and does here.
+ */
+export declare function loadPluginCode(code: string, require: (name: string) => unknown, options?: LoadOptions): unknown;
+/**
+ * The function the runner calls, from what the code exported: the export
+ * itself if it is a function, else its `execute`, else its `default` if that is
+ * a function. `null` when there is none, which the runner reports as "Plugin
+ * must export an execute function".
+ */
+export declare function executeOf(exported: unknown): ((...args: unknown[]) => unknown) | null;

package/dist/simulate.d.ts

@@ -53,6 +53,10 @@ export interface SimulateOptions {
      * Give `connections` a fake that answers the requests your plugin makes,
      * and assert on what it was asked for — that is a better test of an
      * integration step than any simulation of a provider would be.
+     *
+     * @deprecated for `connections`: only VisualAutomate's own apps act as a
+     * connected account, so a step you build is never given one. Stub `fetch`
+     * through loadPluginCode instead.
      */
     connections?: PluginConnections;
     media?: PluginMedia;

package/dist/types.d.ts

@@ -50,7 +50,10 @@ export interface StorageListResult {
  * ceiling is refused rather than silently dropped.
  */
 export interface PluginStorage {
-    /** Write a file. Bytes may be a string, a Buffer or any typed array. */
+    /**
+     * Write a file. Bytes are a string or a Uint8Array: there is no `Buffer` in a
+     * step's context.
+     */
     put(path: string, data: Uint8Array | string, contentType?: string): Promise<StorageResult>;
     /** Read a file back. `null` when it is not there. */
     get(path: string): Promise<Uint8Array | null>;
@@ -69,6 +72,13 @@ export interface PluginStorage {
      * to between one minute and one hour; the default is fifteen minutes.
      */
     signedUrl(path: string, expiresInSeconds?: number): Promise<string | null>;
+    /**
+     * A link on VisualAutomate's own domain that opens the file, for somebody
+     * with no account: a mail, a message, a page. The storage bucket's own
+     * address (signedUrl) is right for an API that fetches the file; this one is
+     * right for a person. Fifteen minutes unless `expiresInSeconds` says otherwise.
+     */
+    shareUrl(path: string, expiresInSeconds?: number): Promise<string | null>;
     /**
      * Pull a URL straight into storage without the bytes passing through this
      * step. A hundred-megabyte file costs the run no memory and no egress,
@@ -87,14 +97,26 @@ export interface PluginStorage {
  * The account's plan caps how many keys it may hold.
  */
 export interface PluginState {
-    /** The stored value, or `null` when the key has never been set. */
+    /** The stored value, or `null` when the key has never been set or has expired. */
     get(key: string): Promise<unknown>;
+    /**
+     * Store a JSON value, at most 128 KB once encoded. With `ttlSeconds`, which
+     * must be at least 60, it is forgotten after that many seconds.
+     */
     set(key: string, value: unknown, options?: {
         ttlSeconds?: number;
     }): Promise<void>;
     delete(key: string): Promise<void>;
+    /**
+     * The keys under a prefix, each with when it expires (`null` for never).
+     * `complete` is false when there were more than one call returns.
+     */
     list(prefix?: string): Promise<{
-        keys: string[];
+        keys: Array<{
+            key: string;
+            expiresAt: string | null;
+        }>;
+        complete: boolean;
     }>;
 }
 /**
@@ -185,7 +207,14 @@ export interface PluginContext {
     state: PluginState;
     /** ffmpeg. Absent when the server has no sandbox or storage configured. */
     media?: PluginMedia;
-    /** The accounts this step was configured with. Absent when it has none. */
+    /**
+     * The accounts this step was configured with. Absent when it has none.
+     *
+     * @deprecated Only VisualAutomate's own apps act as a connected account, so
+     * a step you build never has this: the platform refuses a step that names
+     * an account. Take the user's key in a property of type "secret" and send
+     * it to the API's own host with fetch.
+     */
     connections?: PluginConnections;
 }
 /**
@@ -262,7 +291,14 @@ export type PluginPropertyType = "string" | "number" | "boolean" | "select" | "m
  * `json` above: that one keeps its value structured, so `return 5` would be
  * saved as the number five and the step would run nothing.
  */
- | "code" | "color" | "date"
+ | "code"
+/**
+ * A key the user types in: an API key, a token. A string to your code and to
+ * a declared call (`Bearer {{config.apiKey}}`), and masked wherever it is
+ * shown, because it is the one value on a step that somebody looking over a
+ * shoulder must not be able to read off.
+ */
+ | "secret" | "color" | "date"
 /** An account the user connected. Rendered as a picker, not a text box. */
  | "connection"
 /**
@@ -301,6 +337,49 @@ export interface PluginProperty {
      * `outlook`. A module inherits its app's, so it does not repeat this.
      */
     provider?: string;
+    /** Longer help, shown on request rather than under the input. */
+    help?: string;
+    /** Shown but not editable. */
+    disabled?: boolean;
+    /**
+     * For `select` and `multiselect`: read the options from the user's account
+     * instead of listing them, e.g. the channels of the chosen Slack workspace.
+     */
+    optionsFrom?: OptionsSource;
+    /**
+     * For `secret`: the properties that say where this secret is sent, such as
+     * a server URL. A stored secret is only kept when those are unchanged, so
+     * pointing the URL somewhere else cannot carry the key along.
+     */
+    sentTo?: string[];
+    /**
+     * For `secret`: the value is sent exactly as typed and never computed with,
+     * which lets the platform keep it out of the step's code entirely.
+     */
+    verbatim?: boolean;
+}
+/**
+ * Where a select's options come from: one GET as the account in `connection`,
+ * a list in the answer, and what each option shows and stores.
+ */
+export interface OptionsSource {
+    /** The `connection` property whose account the options are read as. */
+    connection: string;
+    request: {
+        path: string;
+        query?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    };
+    /** Where the list is in the answer (`""` when the answer is the list), and how many to offer. */
+    items: {
+        path: string;
+        limit?: number;
+    };
+    paginate?: Record<string, unknown>;
+    /** What each option shows, e.g. `{{item.name}}`. */
+    label: string;
+    /** What choosing it stores, e.g. `{{item.id}}`. */
+    value: string;
 }
 /**
  * How a step reaches the account it acts as.

package/dist/validate.d.ts

@@ -35,12 +35,3 @@ export declare function validatePluginCode(code: string): CodeCheck;
  * the command that installs the version the sandbox has.
  */
 export declare function sandboxRequire(load: (name: string) => unknown): (name: string) => unknown;
-/**
- * Evaluate a step's code the way the sandbox wraps it: as the body of a function
- * given `module`, `exports` and `require`, in strict mode. Returns what it exported.
- *
- * Not a security boundary — this runs your own code on your own machine. It is
- * here so a file the sandbox cannot load (an `export` statement, a top-level
- * `await`) fails here too, rather than passing a looser loader.
- */
-export declare function loadPluginCode(code: string, require: (name: string) => unknown): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visualautomate/plugin-sdk",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Types and a local runner for building VisualAutomate plugins.",
   "license": "MIT",
   "type": "module",