viasocket-apps 0.3.0 → 0.5.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,49 @@ 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.
+
+## AI assistant
+
+A chat assistant we run for each of your users: threads and history kept per user, your prompt per
+call, your own endpoints as its tools — one of which can run an action in the user's apps. Backend
+only, like everything else here: the prompt and the tools' headers are yours.
+
+```js
+const reply = await user.ai.send({
+  threadId: 'support-7f3a9c', // your own string per conversation; omit to start one
+  message: 'Where is the order for customer 4471?',
+  prompt: 'You are an order assistant. Use lookup_order to fetch orders. Answer in one sentence.',
+  tools: [
+    {
+      name: 'lookup_order',
+      description: 'Fetches an order by customer id',
+      url: 'https://api.your-product.com/orders/lookup',
+      headers: { Authorization: `Bearer ${process.env.ORDERS_API_KEY}` },
+      fields: { id: { type: 'string', description: 'Customer id to look up' } },
+      requiredParams: ['id']
+    }
+  ]
+})
+reply.content // the answer; with responseType 'json_object' or 'json_schema', the parsed object
+
+const threads = await user.ai.threads() // [{ threadId, title, updatedAt }] — title is null until the AI writes it
+const page = await user.ai.history(threadId, { page: 1 }) // { messages, page, hasMore } — 40 exchanges a page, page 1 the latest
+const socket = await user.ai.rtlayerToken() // for a chat UI: the browser subscribes with it, then you send with delivery: 'rtlayer'
+```
+
+The whole contract — tools, JSON answers, the websocket path and what arrives on it — is
+[flow.viasocket.com/documentation/ai.md](https://flow.viasocket.com/documentation/ai.md).
 
 ## Methods
 
@@ -151,6 +204,9 @@ minutes between checks, as a string: `"5"` or `"15"`.
 | `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`
@@ -169,7 +225,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

@@ -14,6 +14,9 @@ const errors_js_1 = require("./errors.js");
 const http_js_1 = require("./http.js");
 const token_js_1 = require("./token.js");
 const DEFAULT_API_BASE_URL = 'https://flow-api.viasocket.com';
+/** The AI API's thread id: the product's own string. */
+const AI_THREAD_ID = /^[A-Za-z0-9_-]{1,100}$/;
+const AI_MAX_TOOLS = 20;
 const DEFAULT_RUN_BASE_URL = 'https://flow.sokt.io';
 /** The public catalog: no token, the same data in every environment. */
 const CATALOG = {
@@ -285,6 +288,94 @@ class UserScope {
     enableFlow(scriptId) {
         return this.setFlowStatus(scriptId, 1);
     }
+    /**
+     * 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
+     * everything else here: the prompt and the tools' headers are yours to keep off the browser.
+     * The whole contract is https://flow.viasocket.com/documentation/ai.md.
+     */
+    ai = {
+        /**
+         * Sends one message and returns the answer — or, with `delivery: 'rtlayer'`, the 202's
+         * `channel` the answer will be published on (subscribe to it in the browser before sending).
+         * Refuses, before any request, what the API would refuse: a threadId with other characters,
+         * `rtlayer` without a threadId, a model without its service, a jsonSchema without its responseType.
+         */
+        send: (async (params) => {
+            const body = { message: required('message', params?.message) };
+            if (params.threadId !== undefined) {
+                if (!AI_THREAD_ID.test(params.threadId)) {
+                    throw new errors_js_1.ViaSocketError('ai.send: threadId is letters, digits, - and _, up to 100 characters', { status: null });
+                }
+                body.thread_id = params.threadId;
+            }
+            if (params.delivery === 'rtlayer' && !params.threadId) {
+                throw new errors_js_1.ViaSocketError('ai.send: threadId is required with delivery "rtlayer" — subscribe to its channel, then send', { status: null });
+            }
+            if (params.prompt !== undefined)
+                body.prompt = params.prompt;
+            if (params.responseType)
+                body.response_type = params.responseType;
+            if (params.jsonSchema) {
+                if (params.responseType !== 'json_schema') {
+                    throw new errors_js_1.ViaSocketError('ai.send: jsonSchema is only allowed with responseType "json_schema"', { status: null });
+                }
+                body.json_schema = params.jsonSchema;
+            }
+            if (!params.model !== !params.service)
+                throw new errors_js_1.ViaSocketError('ai.send: model and service go together', { status: null });
+            if (params.model) {
+                body.model = params.model;
+                body.service = params.service;
+            }
+            if (params.tools?.length) {
+                if (params.tools.length > AI_MAX_TOOLS)
+                    throw new errors_js_1.ViaSocketError(`ai.send: at most ${AI_MAX_TOOLS} tools in one call`, { status: null });
+                body.extra_tools = params.tools.map((tool) => ({
+                    name: required('tool.name', tool?.name),
+                    description: required('tool.description', tool?.description),
+                    url: required('tool.url', tool?.url),
+                    method: tool.method ?? 'POST',
+                    headers: tool.headers ?? {},
+                    fields: tool.fields ?? {},
+                    required_params: tool.requiredParams ?? [],
+                    tool_and_variable_path: tool.toolAndVariablePath ?? {}
+                }));
+            }
+            if (params.delivery)
+                body.delivery = params.delivery;
+            const { data } = await this.call('POST', '/embed/ai/message', body);
+            if (params.delivery === 'rtlayer')
+                return { threadId: data.thread_id, messageId: data.message_id, channel: data.channel ?? '' };
+            return { threadId: data.thread_id, messageId: data.message_id, content: data.content ?? '', finishReason: data.finish_reason ?? '' };
+        }),
+        /** This user's threads in this project, most recently active first. */
+        threads: async () => {
+            const { data } = await this.call('GET', '/embed/ai/threads');
+            return (data?.threads ?? []).map((thread) => ({ threadId: thread.thread_id, title: thread.title ?? null, updatedAt: thread.updated_at }));
+        },
+        /** One thread's messages, 40 exchanges a page; page 1 holds the latest, oldest of those first. */
+        history: async (threadId, params = {}) => {
+            const page = Math.max(1, Math.floor(params.page ?? 1));
+            const { data } = await this.call('GET', `/embed/ai/threads/${encodeURIComponent(required('threadId', threadId))}/history?page=${page}`);
+            return {
+                threadId: data.thread_id ?? threadId,
+                messages: (data.messages ?? []).map((message) => ({
+                    role: message.role,
+                    content: message.content,
+                    messageId: message.message_id,
+                    createdAt: message.created_at
+                })),
+                page: data.page ?? page,
+                hasMore: Boolean(data.has_more)
+            };
+        },
+        /** A 48-hour subscribe token for the browser, and the prefix every thread's channel starts with. */
+        rtlayerToken: async () => {
+            const { data } = await this.call('GET', '/embed/ai/rtlayer-token');
+            return { token: data.token, orgId: data.org_id, serviceId: data.service_id, channelPrefix: data.channel_prefix, expiresIn: data.expires_in };
+        }
+    };
     /**
      * Every app this user has connected. Returned as the API sends it: the shape of each entry
      * is not yet documented, so nothing is mapped or dropped here.

package/dist/cjs/index.js

@@ -12,6 +12,7 @@
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
  *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, code: handler })
+ *   const reply = await user.ai.send({ threadId, message, prompt, tools })  // a chat assistant we run for this user
  *
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */

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/dist/esm/client.d.ts

@@ -7,7 +7,7 @@
  * everything else behind `user(id)` makes that distinction structural rather than something a
  * reader has to remember.
  */
-import type { CatalogApp, CatalogVersions, EnableResult, Flow, FlowStatus, ListOptionsParams, ListAppsParams, ListOptionsResult, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';
+import type { AiHistoryPage, AiRtLayerToken, AiSend, AiThread, CatalogApp, CatalogVersions, EnableResult, Flow, FlowStatus, ListOptionsParams, ListAppsParams, ListOptionsResult, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';
 export declare class ViaSocket {
     readonly orgId: string;
     readonly projectId: string;
@@ -108,6 +108,29 @@ export declare class UserScope {
         id: string;
         status: 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
+     * everything else here: the prompt and the tools' headers are yours to keep off the browser.
+     * The whole contract is https://flow.viasocket.com/documentation/ai.md.
+     */
+    readonly ai: {
+        /**
+         * Sends one message and returns the answer — or, with `delivery: 'rtlayer'`, the 202's
+         * `channel` the answer will be published on (subscribe to it in the browser before sending).
+         * Refuses, before any request, what the API would refuse: a threadId with other characters,
+         * `rtlayer` without a threadId, a model without its service, a jsonSchema without its responseType.
+         */
+        send: AiSend;
+        /** This user's threads in this project, most recently active first. */
+        threads: () => Promise<AiThread[]>;
+        /** One thread's messages, 40 exchanges a page; page 1 holds the latest, oldest of those first. */
+        history: (threadId: string, params?: {
+            page?: number;
+        }) => Promise<AiHistoryPage>;
+        /** A 48-hour subscribe token for the browser, and the prefix every thread's channel starts with. */
+        rtlayerToken: () => Promise<AiRtLayerToken>;
+    };
     /**
      * Every app this user has connected. Returned as the API sends it: the shape of each entry
      * is not yet documented, so nothing is mapped or dropped here.

package/dist/esm/client.js

@@ -11,6 +11,9 @@ import { ViaSocketError } from './errors.js';
 import { request } from './http.js';
 import { signEmbedToken } from './token.js';
 const DEFAULT_API_BASE_URL = 'https://flow-api.viasocket.com';
+/** The AI API's thread id: the product's own string. */
+const AI_THREAD_ID = /^[A-Za-z0-9_-]{1,100}$/;
+const AI_MAX_TOOLS = 20;
 const DEFAULT_RUN_BASE_URL = 'https://flow.sokt.io';
 /** The public catalog: no token, the same data in every environment. */
 const CATALOG = {
@@ -281,6 +284,94 @@ export class UserScope {
     enableFlow(scriptId) {
         return this.setFlowStatus(scriptId, 1);
     }
+    /**
+     * 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
+     * everything else here: the prompt and the tools' headers are yours to keep off the browser.
+     * The whole contract is https://flow.viasocket.com/documentation/ai.md.
+     */
+    ai = {
+        /**
+         * Sends one message and returns the answer — or, with `delivery: 'rtlayer'`, the 202's
+         * `channel` the answer will be published on (subscribe to it in the browser before sending).
+         * Refuses, before any request, what the API would refuse: a threadId with other characters,
+         * `rtlayer` without a threadId, a model without its service, a jsonSchema without its responseType.
+         */
+        send: (async (params) => {
+            const body = { message: required('message', params?.message) };
+            if (params.threadId !== undefined) {
+                if (!AI_THREAD_ID.test(params.threadId)) {
+                    throw new ViaSocketError('ai.send: threadId is letters, digits, - and _, up to 100 characters', { status: null });
+                }
+                body.thread_id = params.threadId;
+            }
+            if (params.delivery === 'rtlayer' && !params.threadId) {
+                throw new ViaSocketError('ai.send: threadId is required with delivery "rtlayer" — subscribe to its channel, then send', { status: null });
+            }
+            if (params.prompt !== undefined)
+                body.prompt = params.prompt;
+            if (params.responseType)
+                body.response_type = params.responseType;
+            if (params.jsonSchema) {
+                if (params.responseType !== 'json_schema') {
+                    throw new ViaSocketError('ai.send: jsonSchema is only allowed with responseType "json_schema"', { status: null });
+                }
+                body.json_schema = params.jsonSchema;
+            }
+            if (!params.model !== !params.service)
+                throw new ViaSocketError('ai.send: model and service go together', { status: null });
+            if (params.model) {
+                body.model = params.model;
+                body.service = params.service;
+            }
+            if (params.tools?.length) {
+                if (params.tools.length > AI_MAX_TOOLS)
+                    throw new ViaSocketError(`ai.send: at most ${AI_MAX_TOOLS} tools in one call`, { status: null });
+                body.extra_tools = params.tools.map((tool) => ({
+                    name: required('tool.name', tool?.name),
+                    description: required('tool.description', tool?.description),
+                    url: required('tool.url', tool?.url),
+                    method: tool.method ?? 'POST',
+                    headers: tool.headers ?? {},
+                    fields: tool.fields ?? {},
+                    required_params: tool.requiredParams ?? [],
+                    tool_and_variable_path: tool.toolAndVariablePath ?? {}
+                }));
+            }
+            if (params.delivery)
+                body.delivery = params.delivery;
+            const { data } = await this.call('POST', '/embed/ai/message', body);
+            if (params.delivery === 'rtlayer')
+                return { threadId: data.thread_id, messageId: data.message_id, channel: data.channel ?? '' };
+            return { threadId: data.thread_id, messageId: data.message_id, content: data.content ?? '', finishReason: data.finish_reason ?? '' };
+        }),
+        /** This user's threads in this project, most recently active first. */
+        threads: async () => {
+            const { data } = await this.call('GET', '/embed/ai/threads');
+            return (data?.threads ?? []).map((thread) => ({ threadId: thread.thread_id, title: thread.title ?? null, updatedAt: thread.updated_at }));
+        },
+        /** One thread's messages, 40 exchanges a page; page 1 holds the latest, oldest of those first. */
+        history: async (threadId, params = {}) => {
+            const page = Math.max(1, Math.floor(params.page ?? 1));
+            const { data } = await this.call('GET', `/embed/ai/threads/${encodeURIComponent(required('threadId', threadId))}/history?page=${page}`);
+            return {
+                threadId: data.thread_id ?? threadId,
+                messages: (data.messages ?? []).map((message) => ({
+                    role: message.role,
+                    content: message.content,
+                    messageId: message.message_id,
+                    createdAt: message.created_at
+                })),
+                page: data.page ?? page,
+                hasMore: Boolean(data.has_more)
+            };
+        },
+        /** A 48-hour subscribe token for the browser, and the prefix every thread's channel starts with. */
+        rtlayerToken: async () => {
+            const { data } = await this.call('GET', '/embed/ai/rtlayer-token');
+            return { token: data.token, orgId: data.org_id, serviceId: data.service_id, channelPrefix: data.channel_prefix, expiresIn: data.expires_in };
+        }
+    };
     /**
      * Every app this user has connected. Returned as the API sends it: the shape of each entry
      * is not yet documented, so nothing is mapped or dropped here.

package/dist/esm/index.d.ts

@@ -11,6 +11,7 @@
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
  *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, code: handler })
+ *   const reply = await user.ai.send({ threadId, message, prompt, tools })  // a chat assistant we run for this user
  *
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */
@@ -18,4 +19,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, 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, CatalogApp, CatalogAction, CatalogService, CatalogTrigger, CatalogVersion, CatalogVersions, EnableResult, Envelope, Flow, FlowStatus, ListAppsParams, ListOptionsParams, ListOptionsResult, Option, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';

package/dist/esm/index.js

@@ -11,6 +11,7 @@
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
  *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, code: handler })
+ *   const reply = await user.ai.send({ threadId, message, prompt, tools })  // a chat assistant we run for this user
  *
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */

package/dist/esm/types.d.ts

@@ -132,8 +132,10 @@ interface CatalogEventBase {
     name: string;
     description: 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.
+     * The field schema a form is rendered from; `inputData` follows it. A `dropdown` / `multiselect`
+     * block with no `options` (or with `enableSearchApi` / `willDynamicFetchOptions`), and an
+     * `input groups` block with no children in `steps`, is a picker: fill it with `listOptions`. The
+     * schema carries no generator code.
      */
     input_schema: Record<string, unknown>;
     /** A real response of the action, or a real event payload of the trigger. */
@@ -177,4 +179,113 @@ export interface Envelope<T = unknown> {
     data: T;
     isCached?: boolean;
 }
+/**
+ * The AI API — `user.ai`: a chat assistant viaSocket runs for one end user, with threads and
+ * history kept per `unique_identifier` and your own HTTP endpoints as the tools it may call.
+ */
+/** One HTTP endpoint of yours the assistant may call while answering. */
+export interface AiTool {
+    /** The name the model calls it by, and the name you use in the prompt: letters, digits, underscores. */
+    name: string;
+    /** When to use it, in a sentence or two. The model decides from this. */
+    description: string;
+    /** The endpoint to call: your own backend, with its own auth in `headers`. Never a run URL — its script_id is a credential. */
+    url: string;
+    /** Default POST. */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Headers for that call — your own API key. They stay server-side. */
+    headers?: Record<string, string>;
+    /** The parameters the model may fill, each with a `type` and a `description` it fills from. */
+    fields?: Record<string, {
+        type: string;
+        description?: string;
+        [key: string]: unknown;
+    }>;
+    /** Which of `fields` the model must fill before calling. */
+    requiredParams?: string[];
+    /** Maps prompt variables to tool parameters. Advanced; omit for an ordinary tool. */
+    toolAndVariablePath?: Record<string, unknown>;
+}
+export interface AiSendParams {
+    /** What the user said. */
+    message: string;
+    /**
+     * Your own string per conversation: letters, digits, `-` and `_`, up to 100 characters. Omit to
+     * start a thread and read the id from the reply. Required with `delivery: 'rtlayer'`, so the
+     * browser can subscribe to the thread's channel before the send.
+     */
+    threadId?: string;
+    /**
+     * The system prompt for this call. It is not stored, so send it every time. May use
+     * `{{orgId}}`, `{{projectId}}` and `{{userId}}`. Name the tools in it and say when to use each.
+     */
+    prompt?: string;
+    /** `text` (default); `json_object`; or `json_schema`, which needs `jsonSchema`. */
+    responseType?: 'text' | 'json_object' | 'json_schema';
+    jsonSchema?: {
+        name: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+    /** A model and its provider, always together: `model: 'gpt-5.6-luna', service: 'openai'`. Omit both for the default. */
+    model?: string;
+    service?: string;
+    /** Up to 20. Only the ones this conversation can need. */
+    tools?: AiTool[];
+    /** `sync` (default): the answer in the response. `rtlayer`: a 202 and the answer on the thread's websocket channel. */
+    delivery?: 'sync' | 'rtlayer';
+}
+/** The answer, from a synchronous send. */
+export interface AiReply {
+    threadId: string;
+    messageId: string;
+    /** A string, or the parsed object for a JSON `responseType`. */
+    content: string | Record<string, unknown>;
+    /** `completed`, `truncated` (out of output tokens), or `tool_call` (stopped to call a tool). */
+    finishReason: 'completed' | 'truncated' | 'tool_call' | string;
+}
+/** The acknowledgement of a send with `delivery: 'rtlayer'`; the answer follows on `channel`. */
+export interface AiAccepted {
+    threadId: string;
+    messageId: string;
+    /** `channelPrefix + threadId`, from `rtlayerToken()`. */
+    channel: string;
+}
+export interface AiSend {
+    (params: AiSendParams & {
+        delivery: 'rtlayer';
+    }): Promise<AiAccepted>;
+    (params: AiSendParams & {
+        delivery?: 'sync';
+    }): Promise<AiReply>;
+}
+export interface AiThread {
+    threadId: string;
+    /** Written by the AI from the thread's first message; `null` until then. */
+    title: string | null;
+    updatedAt: string;
+}
+export interface AiMessage {
+    role: 'user' | 'assistant' | string;
+    content: string;
+    /** A user message and its reply share one id. */
+    messageId: string;
+    createdAt: string;
+}
+/** 40 exchanges a page; page 1 holds the latest, in chronological order. */
+export interface AiHistoryPage {
+    threadId: string;
+    messages: AiMessage[];
+    page: number;
+    hasMore: boolean;
+}
+/** What the browser needs to listen for replies: valid 48 hours, this user's threads only. */
+export interface AiRtLayerToken {
+    token: string;
+    orgId: string;
+    serviceId: string;
+    /** A thread's channel is this followed by the threadId. */
+    channelPrefix: string;
+    expiresIn: string;
+}
 export {};

package/package.json

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