viasocket-apps 0.4.0 → 0.5.0

package/README.md

@@ -118,6 +118,38 @@ popup is on the app's own sign-in page a close can only be inferred, and arrives
 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
 
 | Call | What it does |
@@ -172,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`

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/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.4.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",