viasocket-apps 0.3.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
@@ -94,8 +106,17 @@ const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc', actions:
 // 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
 
@@ -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/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,7 +37,10 @@ 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 `action_id`s and `trigger_id`s this product uses (listed under each one in the app's
@@ -35,7 +50,17 @@ export interface ConnectOptions {
     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`. */
@@ -52,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;
     }
 }
 /**
@@ -63,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/package.json

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