viasocket-apps 0.2.0 → 0.4.0

package/README.md

@@ -37,6 +37,18 @@ goes in your server's `.env`. The skill is
 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>`.
 
+Before you ship — with or without an agent — check the code against the live catalog:
+
+```sh
+curl -fsSL https://flow.viasocket.com/viasocket-check.mjs -o viasocket-check.mjs
+node viasocket-check.mjs src
+```
+
+It finds every viaSocket id and URL in your code and says whether each names a real app, action or
+trigger, is used where its call expects that kind of id (the two ids of an action look alike), and
+whether any viasocket URL was built by hand. No dependencies; exits 1 on a failure, so it can be a
+test. It reads no `.env` file and prints no line of code.
+
 ## Server
 
 ```js
@@ -88,14 +100,23 @@ const subscription = await user.subscribe(triggerVersionId, {
 import { connect } from 'viasocket-apps/browser'
 
 // embedToken comes from your backend (user.token()), signed for the signed-in user.
-// actions (optional): the rowids of the actions and triggers you use — the popup then asks only
+// actions (optional): the action_ids and trigger_ids you use — the popup then asks only
 // for their scopes; skipActionSelection goes straight to the app's consent screen.
-const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc', actions: ['<action rowid>'], skipActionSelection: true })
+const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc', actions: ['<action_id>'], skipActionSelection: true })
 // Send authId to your backend, which enables the app and stores the script_id.
 ```
 
-`connect()` rejects with a `ViaSocketConnectError` whose `code` is `'closed'` (the user gave up),
-`'rejected'` (the app said no) or `'script'` (the connect script did not load).
+`serviceId` is the app's `service_id` exactly as the catalog returns it — a bare id such as
+`rowbu58rc`, never the app's name or slug, never the id with a name joined on. `connect()` loads
+viaSocket's connect script from `https://flow.viasocket.com/connect.js` and lets it open the popup;
+that script is the only supported way to open it, so never build a viasocket URL for it by hand.
+
+`connect()` rejects with a `ViaSocketConnectError` whose `code` is `'closed'` (the user seems to
+have given up), `'rejected'` (the app or viaSocket said no), `'invalid'` (`serviceId` is not a
+service id) or `'script'` (the connect script did not load). `'closed'` is best-effort: once the
+popup is on the app's own sign-in page a close can only be inferred, and arrives about a minute
+later; if the user then finishes anyway, `onLateSuccess` is called with the same result a resolved
+`connect()` gives. Treat `'closed'` as "nothing yet", not as a verdict.
 
 ## Methods
 
@@ -108,8 +129,8 @@ const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc', actions:
 | `user.listOptions(actionVersionId, { fieldKey, authId, existingFields })` | The values a field accepts, as `{ options, offset }`. Both response shapes normalised; an unreadable connection (revoked, another user's `auth_id`) throws a `ViaSocketError` with status 400 even though the API answers 200. |
 | `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 empty. No token. |
-| `viasocket.catalog.versions(serviceId)` | Every published action and trigger of one app, as `{ actions, triggers }`, each with its `inputjson` schema and version id. 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. |
 | `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. |
 
@@ -169,7 +190,9 @@ carrying the API's own `message`, the HTTP `status`, and the parsed `body`.
 
 Defaults target production: `https://flow-api.viasocket.com` for the API and
 `https://flow.sokt.io` for running actions. Pass `apiBaseUrl` / `runBaseUrl` to point elsewhere,
-and `scriptUrl` to `connect()` for a non-production connect script.
+and `scriptUrl` to `connect()` for a non-production connect script — the script picks its own API
+and auth hosts from the origin it is served from, so that is that stack's copy
+(`https://dev-flow.viasocket.com/connect.js`).
 
 ## License
 

package/dist/cjs/browser.js

@@ -8,13 +8,23 @@
  * It wraps viaSocket's standalone connect script — the popup, the postMessage handshake, the
  * three message types — behind one promise. Nothing here touches the signing secret: the
  * embedToken comes from your backend, already signed for this end user.
+ *
+ * The script is served by viaSocket at a fixed URL and is the only supported way to open the
+ * popup: it registers the token, hands the session over, opens the right page for its
+ * environment, and listens for the result on both paths it can arrive by (the popup's own
+ * postMessage, and a relay for sign-in pages that sever the popup's link to this page). A
+ * viasocket URL built by hand opens a page that does not exist.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ViaSocketConnectError = void 0;
 exports.loadConnectScript = loadConnectScript;
 exports.connect = connect;
-const DEFAULT_SCRIPT_URL = 'https://embed.viasocket.com/prod-connectcomponent.js';
+const DEFAULT_SCRIPT_URL = 'https://flow.viasocket.com/connect.js';
 const SCRIPT_ID = 'viasocket-connect-script';
+/** A service id is one bare token of letters and digits: `rowo0bqrhj5g`, never `rowo0bqrhj5g_gmail`. */
+const SERVICE_ID = /^[A-Za-z0-9]+$/;
+/** How long a late success is still delivered after `closed` — the script's own bound. */
+const LATE_SUCCESS_WINDOW_MS = 15 * 60 * 1000;
 class ViaSocketConnectError extends Error {
     code;
     serviceId;
@@ -58,11 +68,13 @@ function loadConnectScript(scriptUrl = DEFAULT_SCRIPT_URL) {
     });
     return scriptPromise;
 }
+const RESULT_TYPES = ['viasocket_connection_success', 'viasocket_connection_error', 'viasocket_connection_closed'];
 /**
  * Opens the consent popup for one app and resolves with the connection it creates.
  *
- * Rejects with a ViaSocketConnectError whose `code` says why: 'closed' if the user gave up,
- * 'rejected' if the app said no, 'script' if the connect script could not load.
+ * Rejects with a ViaSocketConnectError whose `code` says why: 'closed' if the user seems to have
+ * given up (best-effort — see `onLateSuccess`), 'rejected' if the app or viaSocket said no,
+ * 'invalid' if the serviceId is not a service id, 'script' if the connect script could not load.
  */
 async function connect(options) {
     const serviceId = options?.serviceId;
@@ -70,36 +82,62 @@ async function connect(options) {
         throw new ViaSocketConnectError('unavailable', serviceId ?? '', 'connect: embedToken is required');
     if (!serviceId)
         throw new ViaSocketConnectError('unavailable', '', 'connect: serviceId is required');
+    if (typeof serviceId !== 'string' || !SERVICE_ID.test(serviceId)) {
+        throw new ViaSocketConnectError('invalid', String(serviceId), `connect: "${serviceId}" is not a service id. Pass the service_id exactly as the catalog returns it (a bare id such as rowo0bqrhj5g), not the app's name or slug, and not the id with a name joined on`);
+    }
     await loadConnectScript(options.scriptUrl);
     const open = window.openViasocketConnection;
     if (typeof open !== 'function') {
         throw new ViaSocketConnectError('script', serviceId, 'The connect script loaded but did not expose openViasocketConnection()');
     }
     return new Promise((resolve, reject) => {
-        const onMessage = (event) => {
+        let closedReported = false;
+        let lateTimer = null;
+        const cleanup = () => {
+            window.removeEventListener('message', onMessage);
+            if (lateTimer)
+                clearTimeout(lateTimer);
+        };
+        const toResult = (payload) => {
+            const connection = (payload.data ?? {});
+            const authId = typeof connection.id === 'string' ? connection.id : '';
+            return authId ? { authId, serviceId, connection } : null;
+        };
+        function onMessage(event) {
             const payload = event?.data;
-            if (!payload || typeof payload.type !== 'string' || !payload.type.startsWith('viasocket_connection'))
+            if (!payload || typeof payload.type !== 'string' || !RESULT_TYPES.includes(payload.type))
                 return;
             // Two apps can be connecting in one page; only this app's messages are ours.
             if (payload.serviceId && payload.serviceId !== serviceId)
                 return;
-            window.removeEventListener('message', onMessage);
+            if (payload.type === 'viasocket_connection_closed') {
+                if (closedReported)
+                    return;
+                closedReported = true;
+                // Keep listening: a close on the app's sign-in page is inferred, and the script still
+                // delivers a success that arrives after it.
+                lateTimer = setTimeout(cleanup, LATE_SUCCESS_WINDOW_MS);
+                reject(new ViaSocketConnectError('closed', serviceId, 'The popup seems to have been closed before the connection finished'));
+                return;
+            }
+            cleanup();
             if (payload.type === 'viasocket_connection_success') {
-                const connection = (payload.data ?? {});
-                const authId = typeof connection.id === 'string' ? connection.id : '';
-                if (!authId) {
+                const result = toResult(payload);
+                if (closedReported) {
+                    if (result)
+                        options.onLateSuccess?.(result);
+                    return;
+                }
+                if (!result) {
                     reject(new ViaSocketConnectError('rejected', serviceId, 'The connection succeeded but carried no id'));
                     return;
                 }
-                resolve({ authId, serviceId, connection });
+                resolve(result);
             }
-            else if (payload.type === 'viasocket_connection_error') {
+            else if (!closedReported) {
                 reject(new ViaSocketConnectError('rejected', serviceId, payload.error?.message || 'The app rejected the connection'));
             }
-            else if (payload.type === 'viasocket_connection_closed') {
-                reject(new ViaSocketConnectError('closed', serviceId, 'The popup was closed before the connection finished'));
-            }
-        };
+        }
         window.addEventListener('message', onMessage);
         const scriptOptions = {};
         if (options.actions?.length)

package/dist/cjs/client.js

@@ -19,7 +19,7 @@ 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/scriolZue69X'
+    versions: 'https://flow.sokt.io/func/scriK4LFg2kc'
 };
 const LIST_LIMIT_MAX = 200;
 function required(name, value) {
@@ -95,9 +95,13 @@ class ViaSocket {
             }));
         },
         /**
-         * Every published action and trigger of one app, with the schema (`inputjson`) a form is
-         * rendered from and the version id the run and subscribe calls take. Empty for an app with
-         * nothing published. Cache it per app; ids are stable and schemas change rarely.
+         * 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
+         * `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 field schema a form is rendered from. `null` for an unknown service id
+         * (the API answers 200 with an empty service); empty arrays for an app with nothing published.
+         * Cache it per app; ids are stable and schemas change rarely.
          */
         versions: async (serviceId) => {
             const { data } = await (0, http_js_1.request)({
@@ -106,8 +110,16 @@ class ViaSocket {
                 body: JSON.stringify({ service_id: required('serviceId', serviceId) }),
                 fetchImpl: this.transport
             });
-            const rows = Array.isArray(data) ? data : [];
-            return { actions: rows.filter((row) => row.type === 'action'), triggers: rows.filter((row) => row.type === 'trigger') };
+            // No `success` key, so the body arrives whole as `data`; tolerate an envelope anyway.
+            const body = (data && 'service' in data ? data : data?.data) ?? {};
+            const service = body.service;
+            if (!service?.name)
+                return null;
+            return {
+                service,
+                actions: Array.isArray(body.actions) ? body.actions : [],
+                triggers: Array.isArray(body.triggers) ? body.triggers : []
+            };
         }
     };
     /** Everything that is done for one of your end users. */

package/dist/esm/browser.d.ts

@@ -7,14 +7,26 @@
  * It wraps viaSocket's standalone connect script — the popup, the postMessage handshake, the
  * three message types — behind one promise. Nothing here touches the signing secret: the
  * embedToken comes from your backend, already signed for this end user.
+ *
+ * The script is served by viaSocket at a fixed URL and is the only supported way to open the
+ * popup: it registers the token, hands the session over, opens the right page for its
+ * environment, and listens for the result on both paths it can arrive by (the popup's own
+ * postMessage, and a relay for sign-in pages that sever the popup's link to this page). A
+ * viasocket URL built by hand opens a page that does not exist.
  */
 export type ConnectErrorCode = 
-/** The user closed the popup before finishing. Nothing was created. */
+/**
+ * The popup seems to have been closed before finishing. Best-effort: once the popup is on the
+ * app's own sign-in page a close can only be inferred, and arrives about a minute later. If the
+ * user in fact finishes after that, `onLateSuccess` is called with the connection.
+ */
 'closed'
-/** The app refused the authorisation. */
+/** The app refused the authorisation, or viaSocket refused the request (an id that names no app). */
  | 'rejected'
 /** The connect script could not be loaded. */
  | 'script'
+/** The `serviceId` is not a bare service id — the app's name, its slug, or an id with a name joined on. */
+ | 'invalid'
 /** Not running in a browser, or the popup could not be opened. */
  | 'unavailable';
 export declare class ViaSocketConnectError extends Error {
@@ -25,16 +37,30 @@ export declare class ViaSocketConnectError extends Error {
 export interface ConnectOptions {
     /** Signed on your backend for the current end user — see `viasocket.user(id).token()`. */
     embedToken: string;
-    /** The app to connect. Its service_id is shown on every app in the Apps API reference. */
+    /**
+     * The app to connect: its `service_id` exactly as the catalog returns it (`rowo0bqrhj5g`).
+     * Never the app's name or slug, never the id with a name joined on.
+     */
     serviceId: string;
     /**
-     * The rowids of the actions and triggers this product uses (each is listed with its action in
-     * the app's document). The popup then asks only for their scopes. Omit to offer every action.
+     * The `action_id`s and `trigger_id`s this product uses (listed under each one in the app's
+     * document and in `catalog.versions()`). The popup then asks only for their scopes. Omit to
+     * offer every action. Never a version id.
      */
     actions?: string[];
     /** With `actions`: skip the action list and open the app's consent screen directly. */
     skipActionSelection?: boolean;
-    /** Where the connect script is served from. Only override for a non-production environment. */
+    /**
+     * Called if the connection completes after `connect()` already rejected with `'closed'` — the
+     * close was inferred while the user was still on the app's sign-in page. Treat it exactly like
+     * a resolved `connect()`.
+     */
+    onLateSuccess?: (result: ConnectResult) => void;
+    /**
+     * Where the connect script is served from. The script picks its API and auth hosts from its
+     * own origin, so for a non-production stack point this at that stack's copy
+     * (`https://dev-flow.viasocket.com/connect.js`).
+     */
     scriptUrl?: string;
 }
 /** The third argument of the connect script's `openViasocketConnection`. */
@@ -51,7 +77,7 @@ export interface ConnectResult {
 }
 declare global {
     interface Window {
-        openViasocketConnection?: (embedToken: string, serviceId: string, options?: ConnectScriptOptions) => void;
+        openViasocketConnection?: (embedToken: string, serviceId: string, options?: ConnectScriptOptions) => Promise<unknown> | void;
     }
 }
 /**
@@ -62,8 +88,9 @@ export declare function loadConnectScript(scriptUrl?: string): Promise<void>;
 /**
  * Opens the consent popup for one app and resolves with the connection it creates.
  *
- * Rejects with a ViaSocketConnectError whose `code` says why: 'closed' if the user gave up,
- * 'rejected' if the app said no, 'script' if the connect script could not load.
+ * Rejects with a ViaSocketConnectError whose `code` says why: 'closed' if the user seems to have
+ * given up (best-effort — see `onLateSuccess`), 'rejected' if the app or viaSocket said no,
+ * 'invalid' if the serviceId is not a service id, 'script' if the connect script could not load.
  */
 export declare function connect(options: ConnectOptions): Promise<ConnectResult>;
 export {};

package/dist/esm/browser.js

@@ -7,9 +7,19 @@
  * It wraps viaSocket's standalone connect script — the popup, the postMessage handshake, the
  * three message types — behind one promise. Nothing here touches the signing secret: the
  * embedToken comes from your backend, already signed for this end user.
+ *
+ * The script is served by viaSocket at a fixed URL and is the only supported way to open the
+ * popup: it registers the token, hands the session over, opens the right page for its
+ * environment, and listens for the result on both paths it can arrive by (the popup's own
+ * postMessage, and a relay for sign-in pages that sever the popup's link to this page). A
+ * viasocket URL built by hand opens a page that does not exist.
  */
-const DEFAULT_SCRIPT_URL = 'https://embed.viasocket.com/prod-connectcomponent.js';
+const DEFAULT_SCRIPT_URL = 'https://flow.viasocket.com/connect.js';
 const SCRIPT_ID = 'viasocket-connect-script';
+/** A service id is one bare token of letters and digits: `rowo0bqrhj5g`, never `rowo0bqrhj5g_gmail`. */
+const SERVICE_ID = /^[A-Za-z0-9]+$/;
+/** How long a late success is still delivered after `closed` — the script's own bound. */
+const LATE_SUCCESS_WINDOW_MS = 15 * 60 * 1000;
 export class ViaSocketConnectError extends Error {
     code;
     serviceId;
@@ -52,11 +62,13 @@ export function loadConnectScript(scriptUrl = DEFAULT_SCRIPT_URL) {
     });
     return scriptPromise;
 }
+const RESULT_TYPES = ['viasocket_connection_success', 'viasocket_connection_error', 'viasocket_connection_closed'];
 /**
  * Opens the consent popup for one app and resolves with the connection it creates.
  *
- * Rejects with a ViaSocketConnectError whose `code` says why: 'closed' if the user gave up,
- * 'rejected' if the app said no, 'script' if the connect script could not load.
+ * Rejects with a ViaSocketConnectError whose `code` says why: 'closed' if the user seems to have
+ * given up (best-effort — see `onLateSuccess`), 'rejected' if the app or viaSocket said no,
+ * 'invalid' if the serviceId is not a service id, 'script' if the connect script could not load.
  */
 export async function connect(options) {
     const serviceId = options?.serviceId;
@@ -64,36 +76,62 @@ export async function connect(options) {
         throw new ViaSocketConnectError('unavailable', serviceId ?? '', 'connect: embedToken is required');
     if (!serviceId)
         throw new ViaSocketConnectError('unavailable', '', 'connect: serviceId is required');
+    if (typeof serviceId !== 'string' || !SERVICE_ID.test(serviceId)) {
+        throw new ViaSocketConnectError('invalid', String(serviceId), `connect: "${serviceId}" is not a service id. Pass the service_id exactly as the catalog returns it (a bare id such as rowo0bqrhj5g), not the app's name or slug, and not the id with a name joined on`);
+    }
     await loadConnectScript(options.scriptUrl);
     const open = window.openViasocketConnection;
     if (typeof open !== 'function') {
         throw new ViaSocketConnectError('script', serviceId, 'The connect script loaded but did not expose openViasocketConnection()');
     }
     return new Promise((resolve, reject) => {
-        const onMessage = (event) => {
+        let closedReported = false;
+        let lateTimer = null;
+        const cleanup = () => {
+            window.removeEventListener('message', onMessage);
+            if (lateTimer)
+                clearTimeout(lateTimer);
+        };
+        const toResult = (payload) => {
+            const connection = (payload.data ?? {});
+            const authId = typeof connection.id === 'string' ? connection.id : '';
+            return authId ? { authId, serviceId, connection } : null;
+        };
+        function onMessage(event) {
             const payload = event?.data;
-            if (!payload || typeof payload.type !== 'string' || !payload.type.startsWith('viasocket_connection'))
+            if (!payload || typeof payload.type !== 'string' || !RESULT_TYPES.includes(payload.type))
                 return;
             // Two apps can be connecting in one page; only this app's messages are ours.
             if (payload.serviceId && payload.serviceId !== serviceId)
                 return;
-            window.removeEventListener('message', onMessage);
+            if (payload.type === 'viasocket_connection_closed') {
+                if (closedReported)
+                    return;
+                closedReported = true;
+                // Keep listening: a close on the app's sign-in page is inferred, and the script still
+                // delivers a success that arrives after it.
+                lateTimer = setTimeout(cleanup, LATE_SUCCESS_WINDOW_MS);
+                reject(new ViaSocketConnectError('closed', serviceId, 'The popup seems to have been closed before the connection finished'));
+                return;
+            }
+            cleanup();
             if (payload.type === 'viasocket_connection_success') {
-                const connection = (payload.data ?? {});
-                const authId = typeof connection.id === 'string' ? connection.id : '';
-                if (!authId) {
+                const result = toResult(payload);
+                if (closedReported) {
+                    if (result)
+                        options.onLateSuccess?.(result);
+                    return;
+                }
+                if (!result) {
                     reject(new ViaSocketConnectError('rejected', serviceId, 'The connection succeeded but carried no id'));
                     return;
                 }
-                resolve({ authId, serviceId, connection });
+                resolve(result);
             }
-            else if (payload.type === 'viasocket_connection_error') {
+            else if (!closedReported) {
                 reject(new ViaSocketConnectError('rejected', serviceId, payload.error?.message || 'The app rejected the connection'));
             }
-            else if (payload.type === 'viasocket_connection_closed') {
-                reject(new ViaSocketConnectError('closed', serviceId, 'The popup was closed before the connection finished'));
-            }
-        };
+        }
         window.addEventListener('message', onMessage);
         const scriptOptions = {};
         if (options.actions?.length)

package/dist/esm/client.d.ts

@@ -29,11 +29,15 @@ export declare class ViaSocket {
          */
         list: (params?: ListAppsParams) => Promise<CatalogApp[]>;
         /**
-         * Every published action and trigger of one app, with the schema (`inputjson`) a form is
-         * rendered from and the version id the run and subscribe calls take. Empty for an app with
-         * nothing published. Cache it per app; ids are stable and schemas change rarely.
+         * 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
+         * `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 field schema a form is rendered from. `null` for an unknown service id
+         * (the API answers 200 with an empty service); empty arrays for an app with nothing published.
+         * Cache it per app; ids are stable and schemas change rarely.
          */
-        versions: (serviceId: string) => Promise<CatalogVersions>;
+        versions: (serviceId: string) => Promise<CatalogVersions | null>;
     };
     /** Everything that is done for one of your end users. */
     user(uniqueIdentifier: string): UserScope;

package/dist/esm/client.js

@@ -16,7 +16,7 @@ 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/scriolZue69X'
+    versions: 'https://flow.sokt.io/func/scriK4LFg2kc'
 };
 const LIST_LIMIT_MAX = 200;
 function required(name, value) {
@@ -92,9 +92,13 @@ export class ViaSocket {
             }));
         },
         /**
-         * Every published action and trigger of one app, with the schema (`inputjson`) a form is
-         * rendered from and the version id the run and subscribe calls take. Empty for an app with
-         * nothing published. Cache it per app; ids are stable and schemas change rarely.
+         * 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
+         * `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 field schema a form is rendered from. `null` for an unknown service id
+         * (the API answers 200 with an empty service); empty arrays for an app with nothing published.
+         * Cache it per app; ids are stable and schemas change rarely.
          */
         versions: async (serviceId) => {
             const { data } = await request({
@@ -103,8 +107,16 @@ export class ViaSocket {
                 body: JSON.stringify({ service_id: required('serviceId', serviceId) }),
                 fetchImpl: this.transport
             });
-            const rows = Array.isArray(data) ? data : [];
-            return { actions: rows.filter((row) => row.type === 'action'), triggers: rows.filter((row) => row.type === 'trigger') };
+            // No `success` key, so the body arrives whole as `data`; tolerate an envelope anyway.
+            const body = (data && 'service' in data ? data : data?.data) ?? {};
+            const service = body.service;
+            if (!service?.name)
+                return null;
+            return {
+                service,
+                actions: Array.isArray(body.actions) ? body.actions : [],
+                triggers: Array.isArray(body.triggers) ? body.triggers : []
+            };
         }
     };
     /** Everything that is done for one of your end users. */

package/dist/esm/index.d.ts

@@ -18,4 +18,4 @@ export { ViaSocket, UserScope } from './client.js';
 export { ViaSocketError } from './errors.js';
 export { signEmbedToken } from './token.js';
 export type { SignEmbedTokenInput } from './token.js';
-export type { CatalogApp, CatalogVersion, CatalogVersions, EnableResult, Envelope, Flow, FlowStatus, ListAppsParams, ListOptionsParams, ListOptionsResult, Option, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';
+export type { CatalogApp, CatalogAction, CatalogService, CatalogTrigger, CatalogVersion, CatalogVersions, EnableResult, Envelope, Flow, FlowStatus, ListAppsParams, ListOptionsParams, ListOptionsResult, Option, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';

package/dist/esm/types.d.ts

@@ -116,24 +116,60 @@ export interface ListAppsParams {
     /** One of the catalog's category names, e.g. "CRM". */
     category?: string;
 }
-/** One published action or trigger version of an app, as the catalog returns it. */
-export interface CatalogVersion {
-    /** The `action_version_id` (or trigger version id) the run and subscribe calls take. */
-    actionversionrecordid: string;
-    type: 'action' | 'trigger' | string;
+/** The app, once, at the top of `catalog.versions()`. */
+export interface CatalogService {
+    service_id: string;
+    /** The display name. The API sends `null` for an unknown id; `versions()` then returns `null` instead of a catalog. */
+    name: string;
+    description: string | null;
+    icon_url: string | null;
+    /** `Auth2.0`, `apikey`, `NoAuth`, … Informational: connect handles it. */
+    auth_type: string | null;
+    /** `false` for an app without sign-in: no connect button, and `'NoAuth'` wherever a call takes an `authId`. */
+    requires_auth: boolean;
+}
+interface CatalogEventBase {
     name: string;
     description: string;
-    /** The field schema a form is rendered from; `inputData` follows it. */
-    inputjson: Record<string, unknown>;
-    sampledata?: unknown;
-    pluginrecordid?: string;
-    iconurl?: string;
-    authtype?: string;
+    /**
+     * The field schema a form is rendered from; `inputData` follows it. A block with a `source` or
+     * `optionsGenerator` key is a picker: fill it with `listOptions`, never by running what the key holds.
+     */
+    input_schema: Record<string, unknown>;
+    /** A real response of the action, or a real event payload of the trigger. */
+    sample_output?: unknown;
+    updated_at?: string;
     [key: string]: unknown;
 }
+/** One published action, its two ids named as the calls take them. */
+export interface CatalogAction extends CatalogEventBase {
+    /**
+     * The action’s own id: what `connect`’s `actions`, an automation step’s `action_id` and the
+     * prebuilt UI’s `open: { actionId }` take. Looks like the version id and is not interchangeable with it.
+     */
+    action_id: string;
+    /** What `runAction` and `listOptions` take — and only those. */
+    action_version_id: string;
+}
+/** One published trigger, its two ids named as the calls take them. */
+export interface CatalogTrigger extends CatalogEventBase {
+    /**
+     * The trigger’s own id: what `connect`’s `actions`, an automation’s `trigger_id` and the prebuilt
+     * UI’s `open: { triggerId }` take. Looks like the version id and is not interchangeable with it.
+     */
+    trigger_id: string;
+    /** What `subscribe` and `listOptions` take — and only those. */
+    trigger_version_id: string;
+    /** Not reliable yet: the API answers `true` for every trigger. */
+    polled?: boolean | null;
+}
+/** @deprecated The catalog no longer returns rows of one shape; use `CatalogAction` and `CatalogTrigger`. */
+export type CatalogVersion = CatalogAction | CatalogTrigger;
+/** What `catalog.versions()` returns for a known app. */
 export interface CatalogVersions {
-    actions: CatalogVersion[];
-    triggers: CatalogVersion[];
+    service: CatalogService;
+    actions: CatalogAction[];
+    triggers: CatalogTrigger[];
 }
 export interface Envelope<T = unknown> {
     success: boolean;
@@ -141,3 +177,4 @@ export interface Envelope<T = unknown> {
     data: T;
     isCached?: boolean;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viasocket-apps",
-  "version": "0.2.0",
+  "version": "0.4.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",