viasocket-apps 0.1.1 → 0.2.0

package/README.md

@@ -15,6 +15,28 @@ The same calls are documented as plain HTTP in your viaSocket dashboard under
 **Integrations → your Apps API integration → API reference**. Use whichever suits your stack;
 this package is a thin, typed layer over those endpoints and adds nothing they don't have.
 
+## For coding agents
+
+[![skills.sh](https://skills.sh/b/Walkover-Web-Solution/viasocket-apps)](https://skills.sh/Walkover-Web-Solution/viasocket-apps)
+
+This repo also carries the **viaSocket integrations skill** — what a coding agent reads to
+integrate any app into your product, with or without this package. Install it into Claude Code,
+Cursor, Codex, Copilot, Gemini CLI, Windsurf, Cline and 20+ other agents:
+
+```sh
+npx skills add Walkover-Web-Solution/viasocket-apps
+```
+
+Add `-g` to install it for every project. No install? Paste this into your agent:
+`Read https://flow.viasocket.com/documentation/skill.md and follow it.`
+
+The agent needs three values from the viaSocket dashboard (**Integrations → Create embed →
+Install Code**): `org_id` and `project_id`, which it asks for, and `VIASOCKET_EMBED_SECRET`, which
+goes in your server's `.env`. The skill is
+[skills/viasocket-integrations/SKILL.md](skills/viasocket-integrations/SKILL.md), generated by
+viaSocket and mirrored here; the same text filled with your ids is served at
+`https://flow.viasocket.com/documentation/skill.md?org=<org_id>&project=<project_id>`.
+
 ## Server
 
 ```js
@@ -49,12 +71,14 @@ const result = await viasocket.runAction(scriptId, actionVersionId, {
   column_key: true
 })
 
-// 5. Or subscribe to an event. Needs only the connection, not enable().
+// 5. Or subscribe to an event. Needs only the connection, not enable(). `code` is a handler we
+//    run on our servers when the event fires — see "Events" below. Save the scriptId it returns
+//    together with the inputData and handler you sent: the flows list never returns those.
 const subscription = await user.subscribe(triggerVersionId, {
   authId,
   inputData: { channel_id: ['C08SXCV3J85'] },
-  webhook: 'https://your-app.com/webhooks/viasocket',
-  meta: { userId: 'user_123' }
+  code: handler,
+  meta: { user_id: 'user_123' }
 })
 ```
 
@@ -64,7 +88,9 @@ const subscription = await user.subscribe(triggerVersionId, {
 import { connect } from 'viasocket-apps/browser'
 
 // embedToken comes from your backend (user.token()), signed for the signed-in user.
-const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc' })
+// actions (optional): the rowids of the actions and triggers you use — the popup then asks only
+// for their scopes; skipActionSelection goes straight to the app's consent screen.
+const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc', actions: ['<action rowid>'], skipActionSelection: true })
 // Send authId to your backend, which enables the app and stores the script_id.
 ```
 
@@ -79,27 +105,48 @@ const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc' })
 | `user.token()` | Signed embed token for that user; hand it to the frontend. |
 | `user.enable(serviceId, authId)` | Turn a connection into a `scriptId` for running actions. Once per connection. |
 | `user.findEnabled(serviceId)` | The `scriptId` if this app is already enabled, else `null`. Call before `enable`. |
-| `user.listOptions(actionVersionId, { fieldKey, authId, existingFields })` | The values a field accepts, as `{ options, offset }`. Both response shapes normalised. |
+| `user.listOptions(actionVersionId, { fieldKey, authId, existingFields })` | The values a field accepts, as `{ options, offset }`. Both response shapes normalised; an unreadable connection (revoked, another user's `auth_id`) throws a `ViaSocketError` with status 400 even though the API answers 200. |
 | `viasocket.runAction(scriptId, actionVersionId, inputData)` | Run one action. Returns the app's own response. |
-| `user.subscribe(triggerVersionId, { authId, inputData, webhook \| code, meta })` | Subscribe to an app event. Returns `{ scriptId, hookUrl, … }`. |
+| `viasocket.catalog.search(key)` | The best 30 apps for what the user typed, as `{ serviceId, name, iconUrl, description }`. No token. |
+| `viasocket.catalog.list({ limit, offset, category })` | Every app, most used first, 200 a page; an empty page ends it. Drop apps whose `versions()` is empty. No token. |
+| `viasocket.catalog.versions(serviceId)` | Every published action and trigger of one app, as `{ actions, triggers }`, each with its `inputjson` schema and version id. No token. |
+| `user.subscribe(triggerVersionId, { authId, inputData, code \| webhook, meta })` | Subscribe to an app event with a handler we run per event. Returns `{ scriptId, hookUrl, … }`. |
 | `user.updateSubscription(scriptId, { code, meta })` | Change a live subscription in place. |
 
-`webhook` is a URL of yours that we POST each event to. `code` is the alternative: a script we run
-on viaSocket's servers each time the event fires. It is a string, executed away from your process,
-so it must stand alone — no imports, nothing from your codebase. In scope there are `axios`, `fetch`
-and `context`, and the event the app sent is `context.req.body`:
+## Events
+
+Subscribing to an event means telling us **what to do when it fires**. That is `code`: a handler we
+run on viaSocket's servers per event, with the event in `context.req.body`. Your server is not in
+the path. Most often the handler runs an action in another app the user connected — the run URL
+takes no token, the `script_id` is the credential — or calls your own API with your own auth header
+baked in. It is a string executed away from your process, so it must stand alone: no imports,
+nothing from your codebase; `axios`, `fetch` and `context` are in scope.
 
 ```js
-await user.subscribe(triggerVersionId, {
-  authId,
-  inputData,
-  code: `
-    const event = context.req.body
-    await axios.post("https://your-app.com/webhooks/viasocket", { event, user_id: "${endUserId}" })
-    return { forwarded: true }
-  `
-})
+// A string, not a function: it runs on viaSocket's servers each time the event fires.
+// In scope there: axios, fetch, context. The event the app sent is context.req.body.
+// ${…} are YOUR variables, baked in per user when you subscribe.
+const handler = `
+  const event = context.req.body
+  const response = await fetch("https://flow.sokt.io/func/${slackScriptId}", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      action_version_id: "${slackSendMessageVersionId}",
+      inputData: { channel_id: "${channelPickedAtSetup}", text: "New mail from " + event.from + ": " + event.subject }
+    })
+  })
+  return await response.json()
+`
+
+await user.subscribe(gmailNewMailVersionId, { authId, inputData: {}, code: handler, meta: { user_id: uniqueIdentifier } })
 ```
+
+`webhook` is the edge case: a public, unauthenticated URL of yours that we POST every raw event to.
+Use it only when that is what you want, and never both.
+
+Some triggers are polled rather than pushed. For those, `inputData` may carry `scheduledTime`, the
+minutes between checks, as a string: `"5"` or `"15"`.
 | `user.listFlows()` | Every enabled app and subscription this user has. |
 | `user.disableFlow(scriptId)` / `user.enableFlow(scriptId)` | Turn a flow off or back on. Disabling a subscription ends it. |
 | `user.listConnections()` | Every app this user has connected. |

package/dist/cjs/browser.js

@@ -101,6 +101,14 @@ async function connect(options) {
             }
         };
         window.addEventListener('message', onMessage);
-        open(options.embedToken, serviceId);
+        const scriptOptions = {};
+        if (options.actions?.length)
+            scriptOptions.filteredActions = options.actions;
+        if (options.skipActionSelection)
+            scriptOptions.skipActionSelection = true;
+        if (Object.keys(scriptOptions).length)
+            open(options.embedToken, serviceId, scriptOptions);
+        else
+            open(options.embedToken, serviceId);
     });
 }

package/dist/cjs/client.js

@@ -15,6 +15,13 @@ const http_js_1 = require("./http.js");
 const token_js_1 = require("./token.js");
 const DEFAULT_API_BASE_URL = 'https://flow-api.viasocket.com';
 const DEFAULT_RUN_BASE_URL = 'https://flow.sokt.io';
+/** The public catalog: no token, the same data in every environment. */
+const CATALOG = {
+    search: 'https://flow.sokt.io/func/scri12BSufQM',
+    list: 'https://plug-service.viasocket.com/api/v1/plugins/all',
+    versions: 'https://flow.sokt.io/func/scriolZue69X'
+};
+const LIST_LIMIT_MAX = 200;
 function required(name, value) {
     if (typeof value !== 'string' || !value.trim())
         throw new errors_js_1.ViaSocketError(`${name} is required`, { status: null });
@@ -42,6 +49,67 @@ class ViaSocket {
         // Bound so a bare `fetch` reference still has the right `this` on runtimes that care.
         this.transport = options.fetch ? transport : transport.bind(globalThis);
     }
+    /**
+     * The catalog: which apps exist and what each can do. Public, no token, nothing per user — so
+     * it lives on the root client and is safe to call from a browser too.
+     */
+    catalog = {
+        /** The best 30 apps for what the user typed. A type-ahead: an empty key returns nothing. */
+        search: async (key) => {
+            const url = `${CATALOG.search}?key=${encodeURIComponent(required('key', key))}`;
+            const { data } = await (0, http_js_1.request)({ method: 'GET', url, fetchImpl: this.transport });
+            return (Array.isArray(data) ? data : []).map((row) => ({
+                serviceId: row.service_id,
+                name: row.name,
+                description: row.description ?? '',
+                iconUrl: row.iconurl ?? ''
+            }));
+        },
+        /**
+         * Every app, most used first, a page at a time (200 at most). An empty page ends it. The list
+         * is the whole table — far down it holds apps with nothing published — so a grid drops every
+         * app whose `versions()` comes back empty.
+         */
+        list: async (params = {}) => {
+            const query = new URLSearchParams({
+                limit: String(Math.min(Math.max(1, params.limit ?? LIST_LIMIT_MAX), LIST_LIMIT_MAX)),
+                offset: String(Math.max(0, params.offset ?? 0))
+            });
+            if (params.category)
+                query.set('category', params.category);
+            // The body is `{ message, data: [...] }` with no `success` key, so it is not the envelope and
+            // arrives whole as `data`.
+            const { data } = await (0, http_js_1.request)({
+                method: 'GET',
+                url: `${CATALOG.list}?${query}`,
+                fetchImpl: this.transport
+            });
+            const rows = Array.isArray(data) ? data : Array.isArray(data?.data) ? data.data : [];
+            return rows.map((row) => ({
+                serviceId: String(row.rowid ?? ''),
+                name: String(row.name ?? ''),
+                description: String(row.description ?? ''),
+                iconUrl: String(row.iconurl ?? ''),
+                category: Array.isArray(row.category) ? row.category : [],
+                domain: typeof row.domain === 'string' ? row.domain : undefined
+            }));
+        },
+        /**
+         * Every published action and trigger of one app, with the schema (`inputjson`) a form is
+         * rendered from and the version id the run and subscribe calls take. Empty for an app with
+         * nothing published. Cache it per app; ids are stable and schemas change rarely.
+         */
+        versions: async (serviceId) => {
+            const { data } = await (0, http_js_1.request)({
+                method: 'POST',
+                url: CATALOG.versions,
+                body: JSON.stringify({ service_id: required('serviceId', serviceId) }),
+                fetchImpl: this.transport
+            });
+            const rows = Array.isArray(data) ? data : [];
+            return { actions: rows.filter((row) => row.type === 'action'), triggers: rows.filter((row) => row.type === 'trigger') };
+        }
+    };
     /** Everything that is done for one of your end users. */
     user(uniqueIdentifier) {
         return new UserScope(this, required('uniqueIdentifier', uniqueIdentifier));
@@ -124,16 +192,22 @@ class UserScope {
         });
         if (Array.isArray(data))
             return { options: data, offset: null };
+        // A connection that cannot be read (revoked, or another user's auth_id) is answered with 200 and
+        // success: true, the failure nested in data. It is an error, and the message is the explanation.
+        if (data?.response && Number(data.response.status) >= 400) {
+            throw new errors_js_1.ViaSocketError(data.response.data?.message || 'list-options failed', { status: Number(data.response.status), body: data });
+        }
         return { options: Array.isArray(data?.data) ? data.data : [], offset: data?.offset ?? null };
     }
     /**
-     * Subscribes to an app event. Give `webhook` (a URL we POST each event to) or `code` (a
-     * self-contained script we run on our servers per event, with the event at
-     * `context.req.body`) — one or the other.
+     * Subscribes to an app event with a handler: `code`, a self-contained script we run on our
+     * servers each time the event fires, with the event at `context.req.body`. It runs an action in
+     * another app the user connected, or calls your own API. `webhook` (a public URL we POST raw
+     * events to) is the edge case. Exactly one of the two.
      */
     async subscribe(triggerVersionId, params) {
         if (!params?.webhook === !params?.code) {
-            throw new errors_js_1.ViaSocketError('subscribe: pass exactly one of `webhook` or `code`', { status: null });
+            throw new errors_js_1.ViaSocketError('subscribe: pass exactly one of `code` (a handler we run per event) or `webhook`', { status: null });
         }
         const body = {
             auth_id: required('authId', params.authId),

package/dist/cjs/http.js

@@ -8,10 +8,11 @@
  * that message is almost always the explanation.
  *
  * The action runner is the exception: some actions answer in that envelope, many hand back their
- * own result at the top level with no `success` or `data` key at all (Gmail's list-mails returns
- * `{ emails, nextPageToken }`). So a body only counts as an envelope when it actually carries a
- * boolean `success`; anything else is the result itself. Getting this wrong returned `undefined`
- * for every such action.
+ * own result at the top level — with no `success` or `data` key at all (Gmail's list-mails returns
+ * `{ emails, nextPageToken }`), or with a `success` key of their own and no `data` (Slack's "Find
+ * Public channel" returns `{ success, channels }`). So a body is the envelope only when it carries a
+ * boolean `success` AND a `data` key, or is a refusal (`success: false`); anything else is the
+ * result itself. Getting this wrong returned `undefined` for every such action.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.request = request;
@@ -35,7 +36,8 @@ async function request(options) {
     catch {
         payload = text;
     }
-    const isEnvelope = payload !== null && typeof payload === 'object' && typeof payload.success === 'boolean';
+    const shaped = payload !== null && typeof payload === 'object' ? payload : null;
+    const isEnvelope = shaped !== null && typeof shaped.success === 'boolean' && ('data' in shaped || shaped.success === false);
     const envelope = isEnvelope ? payload : null;
     if (!response.ok || envelope?.success === false) {
         const raw = payload && typeof payload === 'object' ? payload : null;

package/dist/cjs/index.js

@@ -5,13 +5,13 @@
  *   import { ViaSocket } from 'viasocket-apps'
  *
  *   const viasocket = new ViaSocket({ orgId, projectId, secret: process.env.VIASOCKET_EMBED_SECRET })
- *   const user = viasocket.user(endUserId)
+ *   const user = viasocket.user(uniqueIdentifier)
  *
  *   const token = await user.token()                                  // for the connect popup
  *   const { scriptId } = await user.enable(serviceId, authId)          // once, for actions
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
- *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, webhook })
+ *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, code: handler })
  *
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */

package/dist/esm/browser.d.ts

@@ -27,9 +27,21 @@ export interface ConnectOptions {
     embedToken: string;
     /** The app to connect. Its service_id is shown on every app in the Apps API reference. */
     serviceId: string;
+    /**
+     * The rowids of the actions and triggers this product uses (each is listed with its action in
+     * the app's document). The popup then asks only for their scopes. Omit to offer every action.
+     */
+    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. */
     scriptUrl?: string;
 }
+/** The third argument of the connect script's `openViasocketConnection`. */
+interface ConnectScriptOptions {
+    filteredActions?: string[];
+    skipActionSelection?: boolean;
+}
 export interface ConnectResult {
     /** The connection. Every later call for this app takes it as auth_id. */
     authId: string;
@@ -39,7 +51,7 @@ export interface ConnectResult {
 }
 declare global {
     interface Window {
-        openViasocketConnection?: (embedToken: string, serviceId: string) => void;
+        openViasocketConnection?: (embedToken: string, serviceId: string, options?: ConnectScriptOptions) => void;
     }
 }
 /**
@@ -54,3 +66,4 @@ export declare function loadConnectScript(scriptUrl?: string): Promise<void>;
  * 'rejected' if the app said no, 'script' if the connect script could not load.
  */
 export declare function connect(options: ConnectOptions): Promise<ConnectResult>;
+export {};

package/dist/esm/browser.js

@@ -95,6 +95,14 @@ export async function connect(options) {
             }
         };
         window.addEventListener('message', onMessage);
-        open(options.embedToken, serviceId);
+        const scriptOptions = {};
+        if (options.actions?.length)
+            scriptOptions.filteredActions = options.actions;
+        if (options.skipActionSelection)
+            scriptOptions.skipActionSelection = true;
+        if (Object.keys(scriptOptions).length)
+            open(options.embedToken, serviceId, scriptOptions);
+        else
+            open(options.embedToken, serviceId);
     });
 }

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 { EnableResult, Flow, FlowStatus, ListOptionsParams, ListOptionsResult, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';
+import type { 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;
@@ -15,6 +15,26 @@ export declare class ViaSocket {
     readonly runBaseUrl: string;
     private readonly secret;
     constructor(options: ViaSocketOptions);
+    /**
+     * The catalog: which apps exist and what each can do. Public, no token, nothing per user — so
+     * it lives on the root client and is safe to call from a browser too.
+     */
+    readonly catalog: {
+        /** The best 30 apps for what the user typed. A type-ahead: an empty key returns nothing. */
+        search: (key: string) => Promise<CatalogApp[]>;
+        /**
+         * Every app, most used first, a page at a time (200 at most). An empty page ends it. The list
+         * is the whole table — far down it holds apps with nothing published — so a grid drops every
+         * app whose `versions()` comes back empty.
+         */
+        list: (params?: ListAppsParams) => Promise<CatalogApp[]>;
+        /**
+         * Every published action and trigger of one app, with the schema (`inputjson`) a form is
+         * rendered from and the version id the run and subscribe calls take. Empty for an app with
+         * nothing published. Cache it per app; ids are stable and schemas change rarely.
+         */
+        versions: (serviceId: string) => Promise<CatalogVersions>;
+    };
     /** Everything that is done for one of your end users. */
     user(uniqueIdentifier: string): UserScope;
     /**
@@ -56,9 +76,10 @@ export declare class UserScope {
      */
     listOptions(actionVersionId: string, params: ListOptionsParams): Promise<ListOptionsResult>;
     /**
-     * Subscribes to an app event. Give `webhook` (a URL we POST each event to) or `code` (a
-     * self-contained script we run on our servers per event, with the event at
-     * `context.req.body`) — one or the other.
+     * Subscribes to an app event with a handler: `code`, a self-contained script we run on our
+     * servers each time the event fires, with the event at `context.req.body`. It runs an action in
+     * another app the user connected, or calls your own API. `webhook` (a public URL we POST raw
+     * events to) is the edge case. Exactly one of the two.
      */
     subscribe(triggerVersionId: string, params: SubscribeParams): Promise<SubscribeResult>;
     /** Changes a live subscription in place. The script_id does not change. */

package/dist/esm/client.js

@@ -12,6 +12,13 @@ import { request } from './http.js';
 import { signEmbedToken } from './token.js';
 const DEFAULT_API_BASE_URL = 'https://flow-api.viasocket.com';
 const DEFAULT_RUN_BASE_URL = 'https://flow.sokt.io';
+/** The public catalog: no token, the same data in every environment. */
+const CATALOG = {
+    search: 'https://flow.sokt.io/func/scri12BSufQM',
+    list: 'https://plug-service.viasocket.com/api/v1/plugins/all',
+    versions: 'https://flow.sokt.io/func/scriolZue69X'
+};
+const LIST_LIMIT_MAX = 200;
 function required(name, value) {
     if (typeof value !== 'string' || !value.trim())
         throw new ViaSocketError(`${name} is required`, { status: null });
@@ -39,6 +46,67 @@ export class ViaSocket {
         // Bound so a bare `fetch` reference still has the right `this` on runtimes that care.
         this.transport = options.fetch ? transport : transport.bind(globalThis);
     }
+    /**
+     * The catalog: which apps exist and what each can do. Public, no token, nothing per user — so
+     * it lives on the root client and is safe to call from a browser too.
+     */
+    catalog = {
+        /** The best 30 apps for what the user typed. A type-ahead: an empty key returns nothing. */
+        search: async (key) => {
+            const url = `${CATALOG.search}?key=${encodeURIComponent(required('key', key))}`;
+            const { data } = await request({ method: 'GET', url, fetchImpl: this.transport });
+            return (Array.isArray(data) ? data : []).map((row) => ({
+                serviceId: row.service_id,
+                name: row.name,
+                description: row.description ?? '',
+                iconUrl: row.iconurl ?? ''
+            }));
+        },
+        /**
+         * Every app, most used first, a page at a time (200 at most). An empty page ends it. The list
+         * is the whole table — far down it holds apps with nothing published — so a grid drops every
+         * app whose `versions()` comes back empty.
+         */
+        list: async (params = {}) => {
+            const query = new URLSearchParams({
+                limit: String(Math.min(Math.max(1, params.limit ?? LIST_LIMIT_MAX), LIST_LIMIT_MAX)),
+                offset: String(Math.max(0, params.offset ?? 0))
+            });
+            if (params.category)
+                query.set('category', params.category);
+            // The body is `{ message, data: [...] }` with no `success` key, so it is not the envelope and
+            // arrives whole as `data`.
+            const { data } = await request({
+                method: 'GET',
+                url: `${CATALOG.list}?${query}`,
+                fetchImpl: this.transport
+            });
+            const rows = Array.isArray(data) ? data : Array.isArray(data?.data) ? data.data : [];
+            return rows.map((row) => ({
+                serviceId: String(row.rowid ?? ''),
+                name: String(row.name ?? ''),
+                description: String(row.description ?? ''),
+                iconUrl: String(row.iconurl ?? ''),
+                category: Array.isArray(row.category) ? row.category : [],
+                domain: typeof row.domain === 'string' ? row.domain : undefined
+            }));
+        },
+        /**
+         * Every published action and trigger of one app, with the schema (`inputjson`) a form is
+         * rendered from and the version id the run and subscribe calls take. Empty for an app with
+         * nothing published. Cache it per app; ids are stable and schemas change rarely.
+         */
+        versions: async (serviceId) => {
+            const { data } = await request({
+                method: 'POST',
+                url: CATALOG.versions,
+                body: JSON.stringify({ service_id: required('serviceId', serviceId) }),
+                fetchImpl: this.transport
+            });
+            const rows = Array.isArray(data) ? data : [];
+            return { actions: rows.filter((row) => row.type === 'action'), triggers: rows.filter((row) => row.type === 'trigger') };
+        }
+    };
     /** Everything that is done for one of your end users. */
     user(uniqueIdentifier) {
         return new UserScope(this, required('uniqueIdentifier', uniqueIdentifier));
@@ -120,16 +188,22 @@ export class UserScope {
         });
         if (Array.isArray(data))
             return { options: data, offset: null };
+        // A connection that cannot be read (revoked, or another user's auth_id) is answered with 200 and
+        // success: true, the failure nested in data. It is an error, and the message is the explanation.
+        if (data?.response && Number(data.response.status) >= 400) {
+            throw new ViaSocketError(data.response.data?.message || 'list-options failed', { status: Number(data.response.status), body: data });
+        }
         return { options: Array.isArray(data?.data) ? data.data : [], offset: data?.offset ?? null };
     }
     /**
-     * Subscribes to an app event. Give `webhook` (a URL we POST each event to) or `code` (a
-     * self-contained script we run on our servers per event, with the event at
-     * `context.req.body`) — one or the other.
+     * Subscribes to an app event with a handler: `code`, a self-contained script we run on our
+     * servers each time the event fires, with the event at `context.req.body`. It runs an action in
+     * another app the user connected, or calls your own API. `webhook` (a public URL we POST raw
+     * events to) is the edge case. Exactly one of the two.
      */
     async subscribe(triggerVersionId, params) {
         if (!params?.webhook === !params?.code) {
-            throw new ViaSocketError('subscribe: pass exactly one of `webhook` or `code`', { status: null });
+            throw new ViaSocketError('subscribe: pass exactly one of `code` (a handler we run per event) or `webhook`', { status: null });
         }
         const body = {
             auth_id: required('authId', params.authId),

package/dist/esm/http.d.ts

@@ -7,10 +7,11 @@
  * that message is almost always the explanation.
  *
  * The action runner is the exception: some actions answer in that envelope, many hand back their
- * own result at the top level with no `success` or `data` key at all (Gmail's list-mails returns
- * `{ emails, nextPageToken }`). So a body only counts as an envelope when it actually carries a
- * boolean `success`; anything else is the result itself. Getting this wrong returned `undefined`
- * for every such action.
+ * own result at the top level — with no `success` or `data` key at all (Gmail's list-mails returns
+ * `{ emails, nextPageToken }`), or with a `success` key of their own and no `data` (Slack's "Find
+ * Public channel" returns `{ success, channels }`). So a body is the envelope only when it carries a
+ * boolean `success` AND a `data` key, or is a refusal (`success: false`); anything else is the
+ * result itself. Getting this wrong returned `undefined` for every such action.
  */
 import type { Envelope } from './types.js';
 export interface RequestOptions {

package/dist/esm/http.js

@@ -7,10 +7,11 @@
  * that message is almost always the explanation.
  *
  * The action runner is the exception: some actions answer in that envelope, many hand back their
- * own result at the top level with no `success` or `data` key at all (Gmail's list-mails returns
- * `{ emails, nextPageToken }`). So a body only counts as an envelope when it actually carries a
- * boolean `success`; anything else is the result itself. Getting this wrong returned `undefined`
- * for every such action.
+ * own result at the top level — with no `success` or `data` key at all (Gmail's list-mails returns
+ * `{ emails, nextPageToken }`), or with a `success` key of their own and no `data` (Slack's "Find
+ * Public channel" returns `{ success, channels }`). So a body is the envelope only when it carries a
+ * boolean `success` AND a `data` key, or is a refusal (`success: false`); anything else is the
+ * result itself. Getting this wrong returned `undefined` for every such action.
  */
 import { ViaSocketError } from './errors.js';
 export async function request(options) {
@@ -32,7 +33,8 @@ export async function request(options) {
     catch {
         payload = text;
     }
-    const isEnvelope = payload !== null && typeof payload === 'object' && typeof payload.success === 'boolean';
+    const shaped = payload !== null && typeof payload === 'object' ? payload : null;
+    const isEnvelope = shaped !== null && typeof shaped.success === 'boolean' && ('data' in shaped || shaped.success === false);
     const envelope = isEnvelope ? payload : null;
     if (!response.ok || envelope?.success === false) {
         const raw = payload && typeof payload === 'object' ? payload : null;

package/dist/esm/index.d.ts

@@ -4,13 +4,13 @@
  *   import { ViaSocket } from 'viasocket-apps'
  *
  *   const viasocket = new ViaSocket({ orgId, projectId, secret: process.env.VIASOCKET_EMBED_SECRET })
- *   const user = viasocket.user(endUserId)
+ *   const user = viasocket.user(uniqueIdentifier)
  *
  *   const token = await user.token()                                  // for the connect popup
  *   const { scriptId } = await user.enable(serviceId, authId)          // once, for actions
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
- *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, webhook })
+ *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, code: handler })
  *
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */
@@ -18,4 +18,4 @@ export { ViaSocket, UserScope } from './client.js';
 export { ViaSocketError } from './errors.js';
 export { signEmbedToken } from './token.js';
 export type { SignEmbedTokenInput } from './token.js';
-export type { EnableResult, Envelope, Flow, FlowStatus, ListOptionsParams, ListOptionsResult, Option, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';
+export type { CatalogApp, CatalogVersion, CatalogVersions, EnableResult, Envelope, Flow, FlowStatus, ListAppsParams, ListOptionsParams, ListOptionsResult, Option, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';

package/dist/esm/index.js

@@ -4,13 +4,13 @@
  *   import { ViaSocket } from 'viasocket-apps'
  *
  *   const viasocket = new ViaSocket({ orgId, projectId, secret: process.env.VIASOCKET_EMBED_SECRET })
- *   const user = viasocket.user(endUserId)
+ *   const user = viasocket.user(uniqueIdentifier)
  *
  *   const token = await user.token()                                  // for the connect popup
  *   const { scriptId } = await user.enable(serviceId, authId)          // once, for actions
  *   const { options } = await user.listOptions(actionVersionId, {...}) // fill a dropdown
  *   const result = await viasocket.runAction(scriptId, actionVersionId, inputData)
- *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, webhook })
+ *   const sub = await user.subscribe(triggerVersionId, { authId, inputData, code: handler })
  *
  * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
  */

package/dist/esm/types.d.ts

@@ -50,19 +50,23 @@ export interface EnableResult {
 }
 export interface SubscribeParams {
     authId: string;
-    /** The event's own configuration — which channel, which sheet. */
+    /**
+     * The event's own configuration — which channel, which sheet. For polled triggers it may also
+     * carry `scheduledTime`, the minutes between checks as a string: "5" or "15".
+     */
     inputData: Record<string, unknown>;
-    /** Your endpoint. We POST every event to it. Use this or `code`, not both. */
-    webhook?: string;
     /**
-     * Instead of a webhook: a script we run on viaSocket's servers each time the event fires.
+     * What to do when the event fires: a script we run on viaSocket's servers per event. The
+     * default. It runs an action in another app the user connected, or calls your own API.
      *
      * It is a string of JavaScript executed away from your process, so it must stand alone — no
      * imports and no reference to anything in your codebase. In scope there: `axios`, `fetch` and
-     * `context`; the event the app sent is `context.req.body`. Bake in any value of yours (a user
-     * id, a URL) when you build the string.
+     * `context`; the event the app sent is `context.req.body`. Bake in any value of yours (a
+     * script_id, a picked id, an API key) when you build the string. Exactly one of `code` or `webhook`.
      */
     code?: string;
+    /** Edge case: a public, unauthenticated URL of yours. We POST every raw event to it. */
+    webhook?: string;
     /** Anything of yours; handed back with every delivery. */
     meta?: Record<string, unknown>;
 }
@@ -94,6 +98,43 @@ export interface Flow {
 }
 export type FlowStatus = 0 | 1;
 /** The envelope every viaSocket endpoint answers with. */
+/** One app of the catalog, from a search or the full list. */
+export interface CatalogApp {
+    /** The `service_id` every other call takes. */
+    serviceId: string;
+    name: string;
+    description: string;
+    iconUrl: string;
+    /** Only the full list carries these. */
+    category?: string[];
+    domain?: string;
+}
+export interface ListAppsParams {
+    /** Up to 200, the API's cap. */
+    limit?: number;
+    offset?: number;
+    /** One of the catalog's category names, e.g. "CRM". */
+    category?: string;
+}
+/** One published action or trigger version of an app, as the catalog returns it. */
+export interface CatalogVersion {
+    /** The `action_version_id` (or trigger version id) the run and subscribe calls take. */
+    actionversionrecordid: string;
+    type: 'action' | 'trigger' | string;
+    name: string;
+    description: string;
+    /** The field schema a form is rendered from; `inputData` follows it. */
+    inputjson: Record<string, unknown>;
+    sampledata?: unknown;
+    pluginrecordid?: string;
+    iconurl?: string;
+    authtype?: string;
+    [key: string]: unknown;
+}
+export interface CatalogVersions {
+    actions: CatalogVersion[];
+    triggers: CatalogVersion[];
+}
 export interface Envelope<T = unknown> {
     success: boolean;
     message?: string;

package/package.json

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