viasocket-apps 0.6.0 → 0.7.0

package/README.md

@@ -31,11 +31,12 @@ Add `-g` to install it for every project. No install? Paste this into your agent
 `Read https://flow.viasocket.com/documentation/skill.md and follow it.`
 
 The agent needs three values from the viaSocket dashboard (**Integrations → Create embed →
-Install Code**): `org_id` and `project_id`, which it asks for, and `VIASOCKET_EMBED_SECRET`, which
-goes in your server's `.env`. The skill is
-[skills/viasocket-integrations/SKILL.md](skills/viasocket-integrations/SKILL.md), generated by
-viaSocket and mirrored here; the same text filled with your ids is served at
-`https://flow.viasocket.com/documentation/skill.md?org=<org_id>&project=<project_id>`.
+Install Code**): `org_id` and `project_id`, which the dashboard's "Copy prompt" hands it, and
+`VIASOCKET_EMBED_SECRET`, which goes in your server's `.env`.
+[skills/viasocket-integrations/SKILL.md](skills/viasocket-integrations/SKILL.md) is the install
+file: the description that makes an agent load the skill, and one instruction — fetch the current
+skill, `https://flow.viasocket.com/documentation/skill.md`, every time it is used — so an install
+never goes stale.
 
 Before you ship — with or without an agent — check the code against the live catalog:
 
@@ -66,7 +67,14 @@ const user = viasocket.user('user_123')
 // 1. Your frontend needs a token to open the connect popup.
 const embedToken = await user.token()
 
-// 2. After the popup posts back an auth_id: enable the app, once, to run actions.
+// The app by its slug, and the event by its action_id and the version your code was written for —
+// both read from the live catalog, never copied ids. Each event's page lists them:
+// https://flow.viasocket.com/documentation/google-sheets.md
+const serviceId = await viasocket.catalog.serviceIdFor('google-sheets')
+const actionVersionId = await viasocket.catalog.versionIdFor(serviceId, '<action_id>', '<version>')
+
+// 2. After the popup posts back an auth_id: enable the app, once, to run actions. A paused app is
+//    found too, and resumed with enableFlow rather than enabled twice.
 const scriptId = (await user.findEnabled(serviceId)) ?? (await user.enable(serviceId, authId)).scriptId
 
 // 3. Fill a dropdown with the user's real data.
@@ -165,9 +173,27 @@ The whole contract — tools, JSON answers, the websocket path and what arrives
 | `viasocket.runAction(scriptId, actionVersionId, inputData)` | Run one action. Returns the app's own response. |
 | `viasocket.catalog.search(key)` | The best 30 apps for what the user typed, as `{ serviceId, name, iconUrl, description }`. No token. |
 | `viasocket.catalog.list({ limit, offset, category })` | Every app, most used first, 200 a page; an empty page ends it. Drop apps whose `versions()` is `null` or empty. No token. |
-| `viasocket.catalog.versions(serviceId)` | One app and every published action and trigger of it, as `{ service, actions, triggers }`. Each action has `action_id` and `action_version_id`, each trigger `trigger_id` and `trigger_version_id`, named as the calls take them: the version id for `runAction`, `listOptions` and `subscribe`; the other for `connect`, automations and the prebuilt UI. `input_schema` is the form schema. `null` for an unknown id. No token. |
+| `viasocket.catalog.versions(serviceId)` | One app and every published action and trigger of it, as `{ service, actions, triggers }`. Each action has `action_id` and `action_version_id`, each trigger `trigger_id` and `trigger_version_id`, named as the calls take them: the version id for `runAction`, `listOptions` and `subscribe`; the other for `connect`, automations and the prebuilt UI. `versionid` is the published version (`V107`). `input_schema` is the form schema. `null` for an unknown id. No token. |
+| `viasocket.catalog.serviceIdFor(slug)` | The `service_id` of the app with this slug (`slack`, `google-sheets`). Exact and case-sensitive; an unknown slug throws. Cached. No token. |
+| `viasocket.catalog.versionIdFor(serviceId, event, version?)` | The version id the calls take, for one event: `event` is its `action_id` / `trigger_id` (survives a rename) or its page path (`send-message`). When the app has published a version other than `version`, it warns and returns the published one. Cached 10 minutes. No token. |
+| `viasocket.catalog.listBuiltIn()` | The built-in plugs (Run AI Model, Pause Workflow, Memory, scraping, GST…): every plug tagged `SDK`, with its actions and whether it needs a sign-in. No token. |
+| `viasocket.sampleEvent(triggerId, authId, authType, inputData?)` | One real event of a trigger for one connection: what a handler reads at `context.req.body`. Takes the `trigger_id`; `authType` is `service.auth_type`. Map from this, never from `sample_output`. |
 | `user.subscribe(triggerVersionId, { authId, inputData, code \| webhook, meta })` | Subscribe to an app event with a handler we run per event. Returns `{ scriptId, hookUrl, … }`. |
 | `user.updateSubscription(scriptId, { code, meta })` | Change a live subscription in place. |
+| `user.listFlows()` | Every enabled app, subscription and automation this user has, each `active`, `paused` or `deleted`. |
+| `user.setFlowStatus(scriptId, n)` | Pause (`2`), resume or restore (`1`), or delete (`0`) one flow. Setting the state it is already in succeeds. |
+| `user.disableFlow(scriptId)` / `user.enableFlow(scriptId)` / `user.deleteFlow(scriptId)` | Pause, resume, delete. |
+| `user.renameFlow(scriptId, { title, description, meta })` | Rename a flow; `meta` comes back as `metadata` in the prebuilt UI's events. |
+| `user.listConnections()` | Every app this user has connected; `isExpired: true` means reconnect it in place with `connect({ authId })`. |
+| `user.revokeConnection(authId)` | Disconnect an app. Pause its flows first. |
+| `user.ai.send({ message, threadId, prompt, tools, responseType, delivery })` | One message to the assistant we run for this user. Returns `{ threadId, messageId, content, finishReason }`, or `{ threadId, messageId, channel }` with `delivery: 'rtlayer'`. |
+| `user.ai.threads()` / `user.ai.history(threadId, { page })` | This user's threads, newest first (`title` is `null` until the AI writes it); one thread's messages, 40 exchanges a page. |
+| `user.ai.rtlayerToken()` | A 48-hour subscribe token for the browser, with the `channelPrefix` every thread's channel starts with. |
+| `signEmbedToken({ orgId, projectId, uniqueIdentifier, secret })` | The signing step on its own, if you want it without a client. |
+
+**Upgrading from 0.6:** `disableFlow` now pauses a flow (status `2`). In 0.6 it sent status `0`,
+which deletes — a deleted flow is still listed as `deleted` and `enableFlow` restores it.
+`findEnabled` now also returns a paused app.
 
 ## Events
 
@@ -189,10 +215,17 @@ const handler = `
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       action_version_id: "${slackSendMessageVersionId}",
-      inputData: { channel_id: "${channelPickedAtSetup}", text: "New mail from " + event.from + ": " + event.subject }
+      // Slack Send Message V107's inputData; the keys of event come from a real sampleEvent
+      inputData: {
+        destination: { messageto: "channel", channel_id: ["${channelPickedAtSetup}"] },
+        markdown_content: "New mail from " + event.from + ": " + event.subject
+      }
     })
   })
-  return await response.json()
+  const result = await response.json()
+  // Envelope { success, data }, or the action's own body: throw so the run history shows the failure.
+  if ("data" in result ? !result.success : result.success === false) throw new Error(result.message || "action failed")
+  return result
 `
 
 await user.subscribe(gmailNewMailVersionId, { authId, inputData: {}, code: handler, meta: { user_id: uniqueIdentifier } })
@@ -203,14 +236,6 @@ Use it only when that is what you want, and never both.
 
 Some triggers are polled rather than pushed. For those, `inputData` may carry `scheduledTime`, the
 minutes between checks, as a string: `"5"` or `"15"`.
-| `user.listFlows()` | Every enabled app and subscription this user has. |
-| `user.disableFlow(scriptId)` / `user.enableFlow(scriptId)` | Turn a flow off or back on. Disabling a subscription ends it. |
-| `user.listConnections()` | Every app this user has connected. |
-| `user.revokeConnection(authId)` | Disconnect an app. Disable its flows first. |
-| `user.ai.send({ message, threadId, prompt, tools, responseType, delivery })` | One message to the assistant we run for this user. Returns `{ threadId, messageId, content, finishReason }`, or `{ threadId, messageId, channel }` with `delivery: 'rtlayer'`. |
-| `user.ai.threads()` / `user.ai.history(threadId, { page })` | This user's threads, newest first (`title` is `null` until the AI writes it); one thread's messages, 40 exchanges a page. |
-| `user.ai.rtlayerToken()` | A 48-hour subscribe token for the browser, with the `channelPrefix` every thread's channel starts with. |
-| `signEmbedToken({ orgId, projectId, uniqueIdentifier, secret })` | The signing step on its own, if you want it without a client. |
 
 Every failure — a non-2xx status or a body with `success: false` — throws a `ViaSocketError`
 carrying the API's own `message`, the HTTP `status`, and the parsed `body`.

package/dist/cjs/client.js

@@ -9,7 +9,7 @@
  * reader has to remember.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UserScope = exports.ViaSocket = void 0;
+exports.UserScope = exports.ViaSocket = exports.BUILT_IN_PLUG_CATEGORIES = void 0;
 const errors_js_1 = require("./errors.js");
 const http_js_1 = require("./http.js");
 const token_js_1 = require("./token.js");
@@ -22,9 +22,25 @@ const DEFAULT_RUN_BASE_URL = 'https://flow.sokt.io';
 const CATALOG = {
     search: 'https://flow.sokt.io/func/scri12BSufQM',
     list: 'https://plug-service.viasocket.com/api/v1/plugins/all',
-    versions: 'https://flow.sokt.io/func/scriK4LFg2kc'
+    versions: 'https://flow.sokt.io/func/scriK4LFg2kc',
+    slug: 'https://plug-service.viasocket.com/api/v1/plugins/recommend/services'
 };
 const LIST_LIMIT_MAX = 200;
+/** The run-host function that fetches one real event of a trigger for one connection. */
+const SAMPLE_EVENT_FUNCTION = 'scrijZpnr8zJ';
+/** Plugs tagged with these categories in Developer Hub are the built-ins `catalog.listBuiltIn()` returns. */
+exports.BUILT_IN_PLUG_CATEGORIES = ['SDK'];
+/** The list answers an empty page for a category with `limit=200`; stay under it. */
+const BUILT_IN_PAGE = 100;
+/** An unknown slug is answered by nothing, slowly; a known one in well under a second. */
+const SLUG_TIMEOUT_MS = 30_000;
+/** How long `versionIdFor` trusts its copy of an app's catalog. */
+const VERSIONS_TTL_MS = 10 * 60_000;
+/** `Send Message` → `send-message`: an event's path on its documentation page. */
+const eventPath = (name) => `${name || ''}`
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
 function required(name, value) {
     if (typeof value !== 'string' || !value.trim())
         throw new errors_js_1.ViaSocketError(`${name} is required`, { status: null });
@@ -39,6 +55,10 @@ class ViaSocket {
     secret;
     /** @internal */
     transport;
+    /** slug → service_id. Slugs never change their app, so for the life of the process. */
+    serviceIds = new Map();
+    /** service_id → its catalog, for `versionIdFor`; a failed read is dropped, never kept. */
+    versionsCache = new Map;
     constructor(options) {
         this.orgId = required('orgId', options?.orgId);
         this.projectId = required('projectId', options?.projectId);
@@ -93,10 +113,77 @@ class ViaSocket {
                 name: String(row.name ?? ''),
                 description: String(row.description ?? ''),
                 iconUrl: String(row.iconurl ?? ''),
+                ...(typeof row.appslugname === 'string' && row.appslugname ? { slug: row.appslugname } : {}),
                 category: Array.isArray(row.category) ? row.category : [],
                 domain: typeof row.domain === 'string' ? row.domain : undefined
             }));
         },
+        /**
+         * The `service_id` of the app with this slug (`slack`, `google-sheets`) — how code names a fixed
+         * app. Exact and case-sensitive; an unknown slug is a ViaSocketError, never a guess (it can take
+         * up to 30 s to be told so). Cached for the life of the process.
+         */
+        serviceIdFor: (slug) => {
+            const key = required('slug', slug);
+            let found = this.serviceIds.get(key);
+            if (!found) {
+                found = this.resolveSlug(key);
+                this.serviceIds.set(key, found);
+                found.catch(() => this.serviceIds.delete(key));
+            }
+            return found;
+        },
+        /**
+         * The version id `runAction`, `listOptions` and `subscribe` take, for one event of an app, read
+         * from the live catalog. `event` is the event's `action_id` / `trigger_id` (it survives a rename)
+         * or its path on the app's page (`send-message`). `version` is the one your code was written
+         * against (`V107`): when the app has published another, this warns and returns the published one —
+         * reread the event's page and update the code. Cached 10 minutes per app.
+         */
+        versionIdFor: async (serviceId, event, version) => {
+            const wanted = required('event', event).trim();
+            const app = await this.cachedVersions(required('serviceId', serviceId));
+            if (!app)
+                throw new errors_js_1.ViaSocketError(`versionIdFor: no app has the service id "${serviceId}"`, { status: null });
+            // Each event with the version id the calls take, whichever kind it is.
+            const all = [
+                ...app.actions.map((e) => ({ id: e.action_id, versionId: e.action_version_id, name: e.name, versionid: e.versionid })),
+                ...app.triggers.map((e) => ({ id: e.trigger_id, versionId: e.trigger_version_id, name: e.name, versionid: e.versionid }))
+            ];
+            const byId = all.filter((e) => e.id === wanted);
+            const found = byId.length ? byId : all.filter((e) => eventPath(e.name) === wanted);
+            if (found.length !== 1) {
+                throw new errors_js_1.ViaSocketError(`versionIdFor: ${app.service.name} has ${found.length ? 'several events' : 'no published event'} "${wanted}" — use its action_id / trigger_id from the app's page`, { status: null });
+            }
+            const [match] = found;
+            if (version && match.versionid && match.versionid !== version) {
+                console.warn(`viaSocket: ${app.service.name} "${wanted}" is published as ${match.versionid}, not ${version}: reread its page and update the code`);
+            }
+            return match.versionId;
+        },
+        /**
+         * The built-in plugs — Run AI Model, Pause Workflow, Memory, scraping, GST and more: every plug
+         * tagged `SDK` in Developer Hub, with its published actions. Live, so a newly tagged plug appears
+         * without a release.
+         */
+        listBuiltIn: async () => {
+            const pages = await Promise.all(exports.BUILT_IN_PLUG_CATEGORIES.map((category) => this.catalog.list({ category, limit: BUILT_IN_PAGE })));
+            const apps = [...new Map(pages.flat().map((app) => [app.serviceId, app])).values()].filter((app) => app.serviceId);
+            const withActions = await Promise.all(apps.map(async (app) => {
+                const versions = await this.catalog.versions(app.serviceId);
+                if (!versions?.actions.length)
+                    return null;
+                return {
+                    serviceId: app.serviceId,
+                    slug: app.slug ?? '',
+                    name: versions.service.name || app.name,
+                    iconUrl: versions.service.icon_url || app.iconUrl,
+                    requiresAuth: versions.service.requires_auth !== false && `${versions.service.auth_type ?? ''}`.toLowerCase() !== 'noauth',
+                    actions: versions.actions
+                };
+            }));
+            return withActions.filter((app) => app !== null).sort((a, b) => a.name.localeCompare(b.name));
+        },
         /**
          * One app and every published action and trigger of it, as `{ service, actions, triggers }`.
          * Each action carries `action_id` and `action_version_id`, each trigger `trigger_id` and
@@ -154,6 +241,78 @@ class ViaSocket {
         });
         return payload.data;
     }
+    /**
+     * One real event of a trigger for one connection: exactly what a handler reads at
+     * `context.req.body`, and what an automation's steps read there. Map from it, never from the
+     * catalog's `sample_output`, which the connector's author recorded on another account. It takes
+     * the `trigger_id` (a version id answers "No response"); `authType` is the app's
+     * `service.auth_type` from `catalog.versions()`; `inputData` is the trigger's own settings, the
+     * same the subscription will carry. No token, but the `auth_id` is a credential: server only.
+     */
+    async sampleEvent(triggerId, authId, authType, inputData = {}) {
+        const query = new URLSearchParams({
+            action_id: required('triggerId', triggerId),
+            auth_id: required('authId', authId),
+            authType: required('authType', authType)
+        });
+        const { data } = await (0, http_js_1.request)({
+            method: 'POST',
+            url: `${this.runBaseUrl}/func/${SAMPLE_EVENT_FUNCTION}?${query}`,
+            body: JSON.stringify({ context: { inputData: inputData ?? {} } }),
+            fetchImpl: this.transport
+        });
+        // An unreadable connection (revoked, another user's, the wrong auth_id) answers 200 with the
+        // failure nested inside, as list-options does.
+        const nested = data?.response;
+        if (nested && Number(nested.status) >= 400) {
+            throw new errors_js_1.ViaSocketError(`sampleEvent: ${nested.data?.message || 'the connection could not be read'}`, {
+                status: Number(nested.status),
+                body: data
+            });
+        }
+        if (!data || typeof data !== 'object' || Array.isArray(data) || data.message === 'No response') {
+            throw new errors_js_1.ViaSocketError(`sampleEvent: no event came back (${JSON.stringify(data)?.slice(0, 120)}) — pass the trigger_id, not its version id, and a live auth_id`, { status: null, body: data });
+        }
+        // `viasocket_help` is a note for the developer, not a field of the event.
+        const { viasocket_help: _help, ...event } = data;
+        return event;
+    }
+    async resolveSlug(slug) {
+        let data;
+        try {
+            ;
+            ({ data } = await (0, http_js_1.request)({
+                method: 'GET',
+                url: `${CATALOG.slug}?service=${encodeURIComponent(slug)}`,
+                fetchImpl: this.transport,
+                signal: AbortSignal.timeout(SLUG_TIMEOUT_MS)
+            }));
+        }
+        catch (error) {
+            if (error?.name !== 'TimeoutError')
+                throw error;
+        }
+        const serviceId = data?.data?.plugins?.[slug]?.rowid;
+        if (!serviceId) {
+            throw new errors_js_1.ViaSocketError(`No viaSocket app has the slug "${slug}" — slugs are exact and case-sensitive; find it with catalog.list()`, {
+                status: null
+            });
+        }
+        return serviceId;
+    }
+    cachedVersions(serviceId) {
+        const cached = this.versionsCache.get(serviceId);
+        if (cached && Date.now() - cached.at < VERSIONS_TTL_MS)
+            return cached.value;
+        const value = this.catalog.versions(serviceId);
+        this.versionsCache.set(serviceId, { at: Date.now(), value });
+        // Neither a failure nor an empty answer is kept: one bad read must not block runs for ten minutes.
+        value.then((app) => {
+            if (!app)
+                this.versionsCache.delete(serviceId);
+        }, () => this.versionsCache.delete(serviceId));
+        return value;
+    }
 }
 exports.ViaSocket = ViaSocket;
 /**
@@ -269,25 +428,56 @@ class UserScope {
         }));
     }
     /**
-     * The script_id of an app this user already enabled, or null. Call it before `enable()` —
-     * enabling twice leaves you with two script_ids for one app.
+     * The script_id of an app this user already enabled — active or paused — or null. Call it before
+     * `enable()`: enabling twice leaves you with two script_ids for one app. A paused one is resumed
+     * with `enableFlow()`, never enabled again.
      */
     async findEnabled(serviceId) {
         const flows = await this.listFlows();
-        return flows.find((flow) => flow.serviceId === required('serviceId', serviceId) && flow.status === 'active')?.id ?? null;
+        const wanted = required('serviceId', serviceId);
+        return flows.find((flow) => flow.serviceId === wanted && (flow.status === 'active' || flow.status === 'paused'))?.id ?? null;
     }
-    /** Turns a flow off (0) or back on (1): an enabled app, or a trigger subscription. */
+    /**
+     * Pauses (2), resumes or restores (1), or deletes (0) one flow: an enabled app, a trigger
+     * subscription or an automation. A deleted flow is listed as `deleted` and can be restored with 1.
+     */
     async setFlowStatus(scriptId, status) {
-        const { data } = await this.call('PUT', `/embed/updatestatus/${required('scriptId', scriptId)}?status=${status}`);
-        // The response is the whole flow record; nothing else in it is anything a caller acts on.
-        return { id: data.id, status: String(data.status) };
+        const id = required('scriptId', scriptId);
+        try {
+            const { data } = await this.call('PUT', `/embed/updatestatus/${id}?status=${status}`);
+            // The response is the whole flow record; nothing else in it is anything a caller acts on.
+            return { id: data.id, status: String(data.status) };
+        }
+        catch (error) {
+            // Already in that state: what the caller asked for is true, so it is not a failure.
+            if (error instanceof errors_js_1.ViaSocketError && /already set/i.test(error.message))
+                return { id, status: String(status) };
+            throw error;
+        }
     }
+    /** Pauses a flow (status 2). Before 0.7.0 this sent 0, which deletes. */
     disableFlow(scriptId) {
-        return this.setFlowStatus(scriptId, 0);
+        return this.setFlowStatus(scriptId, 2);
     }
+    /** Resumes a paused flow, or restores a deleted one (status 1). */
     enableFlow(scriptId) {
         return this.setFlowStatus(scriptId, 1);
     }
+    /** Deletes a flow (status 0). It stays listed as `deleted`; `enableFlow` restores it. */
+    deleteFlow(scriptId) {
+        return this.setFlowStatus(scriptId, 0);
+    }
+    /** Renames a flow; `meta` comes back as `metadata` in the prebuilt UI's flow events. */
+    async renameFlow(scriptId, params) {
+        const body = { title: required('title', params?.title) };
+        if (params.description !== undefined)
+            body.description = params.description;
+        if (params.meta !== undefined)
+            body.meta = params.meta;
+        const { data } = await this.call('PUT', `/projects/updateflowembed/${required('scriptId', scriptId)}`, body);
+        // The response is the whole script, code included; only these are anything a caller acts on.
+        return { id: data.id, title: data.title, description: data.description ?? '' };
+    }
     /**
      * The AI API: a chat assistant viaSocket runs for this user — threads and history kept per
      * `unique_identifier`, your prompt per call, your own endpoints as its tools. Backend only, like

package/dist/cjs/http.js

@@ -23,9 +23,11 @@ async function request(options) {
         headers.authorization = options.token;
     let response;
     try {
-        response = await options.fetchImpl(options.url, { method: options.method, headers, body: options.body });
+        response = await options.fetchImpl(options.url, { method: options.method, headers, body: options.body, signal: options.signal });
     }
     catch (error) {
+        if (error?.name === 'TimeoutError' || error?.name === 'AbortError')
+            throw error;
         throw new errors_js_1.ViaSocketError(`Request to ${options.url} failed: ${error?.message || 'network error'}`, { status: null });
     }
     const text = await response.text();

package/dist/cjs/index.js

@@ -8,6 +8,8 @@
  *   const user = viasocket.user(uniqueIdentifier)
  *
  *   const token = await user.token()                                  // for the connect popup
+ *   const serviceId = await viasocket.catalog.serviceIdFor('slack')    // an app, by its slug
+ *   const actionVersionId = await viasocket.catalog.versionIdFor(serviceId, 'row1jrbor', 'V107')
  *   const { scriptId } = await user.enable(serviceId, authId)          // once, for actions
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
@@ -17,10 +19,11 @@
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.signEmbedToken = exports.ViaSocketError = exports.UserScope = exports.ViaSocket = void 0;
+exports.signEmbedToken = exports.ViaSocketError = exports.BUILT_IN_PLUG_CATEGORIES = exports.UserScope = exports.ViaSocket = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "ViaSocket", { enumerable: true, get: function () { return client_js_1.ViaSocket; } });
 Object.defineProperty(exports, "UserScope", { enumerable: true, get: function () { return client_js_1.UserScope; } });
+Object.defineProperty(exports, "BUILT_IN_PLUG_CATEGORIES", { enumerable: true, get: function () { return client_js_1.BUILT_IN_PLUG_CATEGORIES; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "ViaSocketError", { enumerable: true, get: function () { return errors_js_1.ViaSocketError; } });
 var token_js_1 = require("./token.js");

package/dist/esm/client.d.ts

@@ -7,13 +7,19 @@
  * everything else behind `user(id)` makes that distinction structural rather than something a
  * reader has to remember.
  */
-import type { AiHistoryPage, AiRtLayerToken, AiSend, AiThread, CatalogApp, CatalogVersions, EnableResult, Flow, FlowStatus, ListOptionsParams, ListAppsParams, ListOptionsResult, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';
+import type { AiHistoryPage, AiRtLayerToken, AiSend, AiThread, BuiltInApp, CatalogApp, CatalogVersions, EnableResult, Flow, FlowStatus, ListOptionsParams, ListAppsParams, ListOptionsResult, RenameFlowParams, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';
+/** Plugs tagged with these categories in Developer Hub are the built-ins `catalog.listBuiltIn()` returns. */
+export declare const BUILT_IN_PLUG_CATEGORIES: readonly ["SDK"];
 export declare class ViaSocket {
     readonly orgId: string;
     readonly projectId: string;
     readonly apiBaseUrl: string;
     readonly runBaseUrl: string;
     private readonly secret;
+    /** slug → service_id. Slugs never change their app, so for the life of the process. */
+    private readonly serviceIds;
+    /** service_id → its catalog, for `versionIdFor`; a failed read is dropped, never kept. */
+    private readonly versionsCache;
     constructor(options: ViaSocketOptions);
     /**
      * The catalog: which apps exist and what each can do. Public, no token, nothing per user — so
@@ -28,6 +34,26 @@ export declare class ViaSocket {
          * app whose `versions()` comes back empty.
          */
         list: (params?: ListAppsParams) => Promise<CatalogApp[]>;
+        /**
+         * The `service_id` of the app with this slug (`slack`, `google-sheets`) — how code names a fixed
+         * app. Exact and case-sensitive; an unknown slug is a ViaSocketError, never a guess (it can take
+         * up to 30 s to be told so). Cached for the life of the process.
+         */
+        serviceIdFor: (slug: string) => Promise<string>;
+        /**
+         * The version id `runAction`, `listOptions` and `subscribe` take, for one event of an app, read
+         * from the live catalog. `event` is the event's `action_id` / `trigger_id` (it survives a rename)
+         * or its path on the app's page (`send-message`). `version` is the one your code was written
+         * against (`V107`): when the app has published another, this warns and returns the published one —
+         * reread the event's page and update the code. Cached 10 minutes per app.
+         */
+        versionIdFor: (serviceId: string, event: string, version?: string) => Promise<string>;
+        /**
+         * The built-in plugs — Run AI Model, Pause Workflow, Memory, scraping, GST and more: every plug
+         * tagged `SDK` in Developer Hub, with its published actions. Live, so a newly tagged plug appears
+         * without a release.
+         */
+        listBuiltIn: () => Promise<BuiltInApp[]>;
         /**
          * One app and every published action and trigger of it, as `{ service, actions, triggers }`.
          * Each action carries `action_id` and `action_version_id`, each trigger `trigger_id` and
@@ -51,6 +77,17 @@ export declare class ViaSocket {
      * exactly why this call belongs on your server.
      */
     runAction<T = unknown>(scriptId: string, actionVersionId: string, inputData: Record<string, unknown>): Promise<T>;
+    /**
+     * One real event of a trigger for one connection: exactly what a handler reads at
+     * `context.req.body`, and what an automation's steps read there. Map from it, never from the
+     * catalog's `sample_output`, which the connector's author recorded on another account. It takes
+     * the `trigger_id` (a version id answers "No response"); `authType` is the app's
+     * `service.auth_type` from `catalog.versions()`; `inputData` is the trigger's own settings, the
+     * same the subscription will carry. No token, but the `auth_id` is a credential: server only.
+     */
+    sampleEvent<T = Record<string, unknown>>(triggerId: string, authId: string, authType: string, inputData?: Record<string, unknown>): Promise<T>;
+    private resolveSlug;
+    private cachedVersions;
 }
 /**
  * Calls made on behalf of one end user. Obtained from `viasocket.user(id)`.
@@ -91,23 +128,40 @@ export declare class UserScope {
     /** Every flow this user has: one per enabled app, one per trigger subscription. */
     listFlows(): Promise<Flow[]>;
     /**
-     * The script_id of an app this user already enabled, or null. Call it before `enable()` —
-     * enabling twice leaves you with two script_ids for one app.
+     * The script_id of an app this user already enabled — active or paused — or null. Call it before
+     * `enable()`: enabling twice leaves you with two script_ids for one app. A paused one is resumed
+     * with `enableFlow()`, never enabled again.
      */
     findEnabled(serviceId: string): Promise<string | null>;
-    /** Turns a flow off (0) or back on (1): an enabled app, or a trigger subscription. */
+    /**
+     * Pauses (2), resumes or restores (1), or deletes (0) one flow: an enabled app, a trigger
+     * subscription or an automation. A deleted flow is listed as `deleted` and can be restored with 1.
+     */
     setFlowStatus(scriptId: string, status: FlowStatus): Promise<{
         id: string;
         status: string;
     }>;
+    /** Pauses a flow (status 2). Before 0.7.0 this sent 0, which deletes. */
     disableFlow(scriptId: string): Promise<{
         id: string;
         status: string;
     }>;
+    /** Resumes a paused flow, or restores a deleted one (status 1). */
     enableFlow(scriptId: string): Promise<{
         id: string;
         status: string;
     }>;
+    /** Deletes a flow (status 0). It stays listed as `deleted`; `enableFlow` restores it. */
+    deleteFlow(scriptId: string): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /** Renames a flow; `meta` comes back as `metadata` in the prebuilt UI's flow events. */
+    renameFlow(scriptId: string, params: RenameFlowParams): Promise<{
+        id: string;
+        title: string;
+        description: string;
+    }>;
     /**
      * The AI API: a chat assistant viaSocket runs for this user — threads and history kept per
      * `unique_identifier`, your prompt per call, your own endpoints as its tools. Backend only, like

package/dist/esm/client.js

@@ -19,9 +19,25 @@ const DEFAULT_RUN_BASE_URL = 'https://flow.sokt.io';
 const CATALOG = {
     search: 'https://flow.sokt.io/func/scri12BSufQM',
     list: 'https://plug-service.viasocket.com/api/v1/plugins/all',
-    versions: 'https://flow.sokt.io/func/scriK4LFg2kc'
+    versions: 'https://flow.sokt.io/func/scriK4LFg2kc',
+    slug: 'https://plug-service.viasocket.com/api/v1/plugins/recommend/services'
 };
 const LIST_LIMIT_MAX = 200;
+/** The run-host function that fetches one real event of a trigger for one connection. */
+const SAMPLE_EVENT_FUNCTION = 'scrijZpnr8zJ';
+/** Plugs tagged with these categories in Developer Hub are the built-ins `catalog.listBuiltIn()` returns. */
+export const BUILT_IN_PLUG_CATEGORIES = ['SDK'];
+/** The list answers an empty page for a category with `limit=200`; stay under it. */
+const BUILT_IN_PAGE = 100;
+/** An unknown slug is answered by nothing, slowly; a known one in well under a second. */
+const SLUG_TIMEOUT_MS = 30_000;
+/** How long `versionIdFor` trusts its copy of an app's catalog. */
+const VERSIONS_TTL_MS = 10 * 60_000;
+/** `Send Message` → `send-message`: an event's path on its documentation page. */
+const eventPath = (name) => `${name || ''}`
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
 function required(name, value) {
     if (typeof value !== 'string' || !value.trim())
         throw new ViaSocketError(`${name} is required`, { status: null });
@@ -36,6 +52,10 @@ export class ViaSocket {
     secret;
     /** @internal */
     transport;
+    /** slug → service_id. Slugs never change their app, so for the life of the process. */
+    serviceIds = new Map();
+    /** service_id → its catalog, for `versionIdFor`; a failed read is dropped, never kept. */
+    versionsCache = new Map;
     constructor(options) {
         this.orgId = required('orgId', options?.orgId);
         this.projectId = required('projectId', options?.projectId);
@@ -90,10 +110,77 @@ export class ViaSocket {
                 name: String(row.name ?? ''),
                 description: String(row.description ?? ''),
                 iconUrl: String(row.iconurl ?? ''),
+                ...(typeof row.appslugname === 'string' && row.appslugname ? { slug: row.appslugname } : {}),
                 category: Array.isArray(row.category) ? row.category : [],
                 domain: typeof row.domain === 'string' ? row.domain : undefined
             }));
         },
+        /**
+         * The `service_id` of the app with this slug (`slack`, `google-sheets`) — how code names a fixed
+         * app. Exact and case-sensitive; an unknown slug is a ViaSocketError, never a guess (it can take
+         * up to 30 s to be told so). Cached for the life of the process.
+         */
+        serviceIdFor: (slug) => {
+            const key = required('slug', slug);
+            let found = this.serviceIds.get(key);
+            if (!found) {
+                found = this.resolveSlug(key);
+                this.serviceIds.set(key, found);
+                found.catch(() => this.serviceIds.delete(key));
+            }
+            return found;
+        },
+        /**
+         * The version id `runAction`, `listOptions` and `subscribe` take, for one event of an app, read
+         * from the live catalog. `event` is the event's `action_id` / `trigger_id` (it survives a rename)
+         * or its path on the app's page (`send-message`). `version` is the one your code was written
+         * against (`V107`): when the app has published another, this warns and returns the published one —
+         * reread the event's page and update the code. Cached 10 minutes per app.
+         */
+        versionIdFor: async (serviceId, event, version) => {
+            const wanted = required('event', event).trim();
+            const app = await this.cachedVersions(required('serviceId', serviceId));
+            if (!app)
+                throw new ViaSocketError(`versionIdFor: no app has the service id "${serviceId}"`, { status: null });
+            // Each event with the version id the calls take, whichever kind it is.
+            const all = [
+                ...app.actions.map((e) => ({ id: e.action_id, versionId: e.action_version_id, name: e.name, versionid: e.versionid })),
+                ...app.triggers.map((e) => ({ id: e.trigger_id, versionId: e.trigger_version_id, name: e.name, versionid: e.versionid }))
+            ];
+            const byId = all.filter((e) => e.id === wanted);
+            const found = byId.length ? byId : all.filter((e) => eventPath(e.name) === wanted);
+            if (found.length !== 1) {
+                throw new ViaSocketError(`versionIdFor: ${app.service.name} has ${found.length ? 'several events' : 'no published event'} "${wanted}" — use its action_id / trigger_id from the app's page`, { status: null });
+            }
+            const [match] = found;
+            if (version && match.versionid && match.versionid !== version) {
+                console.warn(`viaSocket: ${app.service.name} "${wanted}" is published as ${match.versionid}, not ${version}: reread its page and update the code`);
+            }
+            return match.versionId;
+        },
+        /**
+         * The built-in plugs — Run AI Model, Pause Workflow, Memory, scraping, GST and more: every plug
+         * tagged `SDK` in Developer Hub, with its published actions. Live, so a newly tagged plug appears
+         * without a release.
+         */
+        listBuiltIn: async () => {
+            const pages = await Promise.all(BUILT_IN_PLUG_CATEGORIES.map((category) => this.catalog.list({ category, limit: BUILT_IN_PAGE })));
+            const apps = [...new Map(pages.flat().map((app) => [app.serviceId, app])).values()].filter((app) => app.serviceId);
+            const withActions = await Promise.all(apps.map(async (app) => {
+                const versions = await this.catalog.versions(app.serviceId);
+                if (!versions?.actions.length)
+                    return null;
+                return {
+                    serviceId: app.serviceId,
+                    slug: app.slug ?? '',
+                    name: versions.service.name || app.name,
+                    iconUrl: versions.service.icon_url || app.iconUrl,
+                    requiresAuth: versions.service.requires_auth !== false && `${versions.service.auth_type ?? ''}`.toLowerCase() !== 'noauth',
+                    actions: versions.actions
+                };
+            }));
+            return withActions.filter((app) => app !== null).sort((a, b) => a.name.localeCompare(b.name));
+        },
         /**
          * One app and every published action and trigger of it, as `{ service, actions, triggers }`.
          * Each action carries `action_id` and `action_version_id`, each trigger `trigger_id` and
@@ -151,6 +238,78 @@ export class ViaSocket {
         });
         return payload.data;
     }
+    /**
+     * One real event of a trigger for one connection: exactly what a handler reads at
+     * `context.req.body`, and what an automation's steps read there. Map from it, never from the
+     * catalog's `sample_output`, which the connector's author recorded on another account. It takes
+     * the `trigger_id` (a version id answers "No response"); `authType` is the app's
+     * `service.auth_type` from `catalog.versions()`; `inputData` is the trigger's own settings, the
+     * same the subscription will carry. No token, but the `auth_id` is a credential: server only.
+     */
+    async sampleEvent(triggerId, authId, authType, inputData = {}) {
+        const query = new URLSearchParams({
+            action_id: required('triggerId', triggerId),
+            auth_id: required('authId', authId),
+            authType: required('authType', authType)
+        });
+        const { data } = await request({
+            method: 'POST',
+            url: `${this.runBaseUrl}/func/${SAMPLE_EVENT_FUNCTION}?${query}`,
+            body: JSON.stringify({ context: { inputData: inputData ?? {} } }),
+            fetchImpl: this.transport
+        });
+        // An unreadable connection (revoked, another user's, the wrong auth_id) answers 200 with the
+        // failure nested inside, as list-options does.
+        const nested = data?.response;
+        if (nested && Number(nested.status) >= 400) {
+            throw new ViaSocketError(`sampleEvent: ${nested.data?.message || 'the connection could not be read'}`, {
+                status: Number(nested.status),
+                body: data
+            });
+        }
+        if (!data || typeof data !== 'object' || Array.isArray(data) || data.message === 'No response') {
+            throw new ViaSocketError(`sampleEvent: no event came back (${JSON.stringify(data)?.slice(0, 120)}) — pass the trigger_id, not its version id, and a live auth_id`, { status: null, body: data });
+        }
+        // `viasocket_help` is a note for the developer, not a field of the event.
+        const { viasocket_help: _help, ...event } = data;
+        return event;
+    }
+    async resolveSlug(slug) {
+        let data;
+        try {
+            ;
+            ({ data } = await request({
+                method: 'GET',
+                url: `${CATALOG.slug}?service=${encodeURIComponent(slug)}`,
+                fetchImpl: this.transport,
+                signal: AbortSignal.timeout(SLUG_TIMEOUT_MS)
+            }));
+        }
+        catch (error) {
+            if (error?.name !== 'TimeoutError')
+                throw error;
+        }
+        const serviceId = data?.data?.plugins?.[slug]?.rowid;
+        if (!serviceId) {
+            throw new ViaSocketError(`No viaSocket app has the slug "${slug}" — slugs are exact and case-sensitive; find it with catalog.list()`, {
+                status: null
+            });
+        }
+        return serviceId;
+    }
+    cachedVersions(serviceId) {
+        const cached = this.versionsCache.get(serviceId);
+        if (cached && Date.now() - cached.at < VERSIONS_TTL_MS)
+            return cached.value;
+        const value = this.catalog.versions(serviceId);
+        this.versionsCache.set(serviceId, { at: Date.now(), value });
+        // Neither a failure nor an empty answer is kept: one bad read must not block runs for ten minutes.
+        value.then((app) => {
+            if (!app)
+                this.versionsCache.delete(serviceId);
+        }, () => this.versionsCache.delete(serviceId));
+        return value;
+    }
 }
 /**
  * Calls made on behalf of one end user. Obtained from `viasocket.user(id)`.
@@ -265,25 +424,56 @@ export class UserScope {
         }));
     }
     /**
-     * The script_id of an app this user already enabled, or null. Call it before `enable()` —
-     * enabling twice leaves you with two script_ids for one app.
+     * The script_id of an app this user already enabled — active or paused — or null. Call it before
+     * `enable()`: enabling twice leaves you with two script_ids for one app. A paused one is resumed
+     * with `enableFlow()`, never enabled again.
      */
     async findEnabled(serviceId) {
         const flows = await this.listFlows();
-        return flows.find((flow) => flow.serviceId === required('serviceId', serviceId) && flow.status === 'active')?.id ?? null;
+        const wanted = required('serviceId', serviceId);
+        return flows.find((flow) => flow.serviceId === wanted && (flow.status === 'active' || flow.status === 'paused'))?.id ?? null;
     }
-    /** Turns a flow off (0) or back on (1): an enabled app, or a trigger subscription. */
+    /**
+     * Pauses (2), resumes or restores (1), or deletes (0) one flow: an enabled app, a trigger
+     * subscription or an automation. A deleted flow is listed as `deleted` and can be restored with 1.
+     */
     async setFlowStatus(scriptId, status) {
-        const { data } = await this.call('PUT', `/embed/updatestatus/${required('scriptId', scriptId)}?status=${status}`);
-        // The response is the whole flow record; nothing else in it is anything a caller acts on.
-        return { id: data.id, status: String(data.status) };
+        const id = required('scriptId', scriptId);
+        try {
+            const { data } = await this.call('PUT', `/embed/updatestatus/${id}?status=${status}`);
+            // The response is the whole flow record; nothing else in it is anything a caller acts on.
+            return { id: data.id, status: String(data.status) };
+        }
+        catch (error) {
+            // Already in that state: what the caller asked for is true, so it is not a failure.
+            if (error instanceof ViaSocketError && /already set/i.test(error.message))
+                return { id, status: String(status) };
+            throw error;
+        }
     }
+    /** Pauses a flow (status 2). Before 0.7.0 this sent 0, which deletes. */
     disableFlow(scriptId) {
-        return this.setFlowStatus(scriptId, 0);
+        return this.setFlowStatus(scriptId, 2);
     }
+    /** Resumes a paused flow, or restores a deleted one (status 1). */
     enableFlow(scriptId) {
         return this.setFlowStatus(scriptId, 1);
     }
+    /** Deletes a flow (status 0). It stays listed as `deleted`; `enableFlow` restores it. */
+    deleteFlow(scriptId) {
+        return this.setFlowStatus(scriptId, 0);
+    }
+    /** Renames a flow; `meta` comes back as `metadata` in the prebuilt UI's flow events. */
+    async renameFlow(scriptId, params) {
+        const body = { title: required('title', params?.title) };
+        if (params.description !== undefined)
+            body.description = params.description;
+        if (params.meta !== undefined)
+            body.meta = params.meta;
+        const { data } = await this.call('PUT', `/projects/updateflowembed/${required('scriptId', scriptId)}`, body);
+        // The response is the whole script, code included; only these are anything a caller acts on.
+        return { id: data.id, title: data.title, description: data.description ?? '' };
+    }
     /**
      * The AI API: a chat assistant viaSocket runs for this user — threads and history kept per
      * `unique_identifier`, your prompt per call, your own endpoints as its tools. Backend only, like

package/dist/esm/http.d.ts

@@ -22,5 +22,7 @@ export interface RequestOptions {
     /** Already serialised. `''` sends an empty body, which is what /embed/enable expects. */
     body?: string;
     fetchImpl: typeof fetch;
+    /** Aborts the request; an abort is thrown as is, so a caller can tell a timeout from a refusal. */
+    signal?: AbortSignal;
 }
 export declare function request<T = unknown>(options: RequestOptions): Promise<Envelope<T>>;

package/dist/esm/http.js

@@ -20,9 +20,11 @@ export async function request(options) {
         headers.authorization = options.token;
     let response;
     try {
-        response = await options.fetchImpl(options.url, { method: options.method, headers, body: options.body });
+        response = await options.fetchImpl(options.url, { method: options.method, headers, body: options.body, signal: options.signal });
     }
     catch (error) {
+        if (error?.name === 'TimeoutError' || error?.name === 'AbortError')
+            throw error;
         throw new ViaSocketError(`Request to ${options.url} failed: ${error?.message || 'network error'}`, { status: null });
     }
     const text = await response.text();

package/dist/esm/index.d.ts

@@ -7,6 +7,8 @@
  *   const user = viasocket.user(uniqueIdentifier)
  *
  *   const token = await user.token()                                  // for the connect popup
+ *   const serviceId = await viasocket.catalog.serviceIdFor('slack')    // an app, by its slug
+ *   const actionVersionId = await viasocket.catalog.versionIdFor(serviceId, 'row1jrbor', 'V107')
  *   const { scriptId } = await user.enable(serviceId, authId)          // once, for actions
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
@@ -15,8 +17,8 @@
  *
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */
-export { ViaSocket, UserScope } from './client.js';
+export { ViaSocket, UserScope, BUILT_IN_PLUG_CATEGORIES } from './client.js';
 export { ViaSocketError } from './errors.js';
 export { signEmbedToken } from './token.js';
 export type { SignEmbedTokenInput } from './token.js';
-export type { AiAccepted, AiHistoryPage, AiMessage, AiReply, AiRtLayerToken, AiSend, AiSendParams, AiThread, AiTool, CatalogApp, CatalogAction, CatalogService, CatalogTrigger, CatalogVersion, CatalogVersions, EnableResult, Envelope, Flow, FlowStatus, ListAppsParams, ListOptionsParams, ListOptionsResult, Option, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';
+export type { AiAccepted, AiHistoryPage, AiMessage, AiReply, AiRtLayerToken, AiSend, AiSendParams, AiThread, AiTool, BuiltInApp, CatalogApp, CatalogAction, CatalogService, CatalogTrigger, CatalogVersion, CatalogVersions, EnableResult, Envelope, Flow, FlowStatus, ListAppsParams, ListOptionsParams, ListOptionsResult, Option, RenameFlowParams, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';

package/dist/esm/index.js

@@ -7,6 +7,8 @@
  *   const user = viasocket.user(uniqueIdentifier)
  *
  *   const token = await user.token()                                  // for the connect popup
+ *   const serviceId = await viasocket.catalog.serviceIdFor('slack')    // an app, by its slug
+ *   const actionVersionId = await viasocket.catalog.versionIdFor(serviceId, 'row1jrbor', 'V107')
  *   const { scriptId } = await user.enable(serviceId, authId)          // once, for actions
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
@@ -15,6 +17,6 @@
  *
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */
-export { ViaSocket, UserScope } from './client.js';
+export { ViaSocket, UserScope, BUILT_IN_PLUG_CATEGORIES } from './client.js';
 export { ViaSocketError } from './errors.js';
 export { signEmbedToken } from './token.js';

package/dist/esm/types.d.ts

@@ -96,7 +96,14 @@ export interface Flow {
     authId: string;
     serviceId: string;
 }
-export type FlowStatus = 0 | 1;
+/** What `setFlowStatus` sets: `2` pauses, `1` resumes or restores, `0` deletes. */
+export type FlowStatus = 0 | 1 | 2;
+export interface RenameFlowParams {
+    title: string;
+    description?: string;
+    /** Anything of yours; comes back as `metadata` in the prebuilt UI's flow events. */
+    meta?: Record<string, unknown>;
+}
 /** The envelope every viaSocket endpoint answers with. */
 /** One app of the catalog, from a search or the full list. */
 export interface CatalogApp {
@@ -105,10 +112,24 @@ export interface CatalogApp {
     name: string;
     description: string;
     iconUrl: string;
-    /** Only the full list carries these. */
+    /**
+     * The app's slug (`slack`, `google-sheets`): what code names a fixed app by, resolved with
+     * `catalog.serviceIdFor`. Case-sensitive. Only the full list carries it, and `category` and `domain`.
+     */
+    slug?: string;
     category?: string[];
     domain?: string;
 }
+/** One built-in plug — `catalog.listBuiltIn()` — with its published actions. */
+export interface BuiltInApp {
+    serviceId: string;
+    slug: string;
+    name: string;
+    iconUrl: string;
+    /** `false`: no Connect button, and `'NoAuth'` wherever a call takes an `authId`. */
+    requiresAuth: boolean;
+    actions: CatalogAction[];
+}
 export interface ListAppsParams {
     /** Up to 200, the API's cap. */
     limit?: number;
@@ -138,7 +159,9 @@ interface CatalogEventBase {
      * schema carries no generator code.
      */
     input_schema: Record<string, unknown>;
-    /** A real response of the action, or a real event payload of the trigger. */
+    /** The published version's name (`V107`): what `versionIdFor` checks the version in your code against. */
+    versionid?: string;
+    /** The connector author's example of the response or event, from another account: map from a real one. */
     sample_output?: unknown;
     updated_at?: string;
     [key: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viasocket-apps",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Server-side client for the viaSocket Apps API: let your users connect Slack, GitHub, Google Sheets or any of 2,300+ apps from your own product, then run actions and receive events through one API.",
   "keywords": [
     "viasocket",