viasocket-apps 0.1.0 → 0.1.2

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' }
 })
 ```
 
@@ -79,10 +103,45 @@ 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, … }`. |
+| `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. |
+
+## 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
+// 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/client.js

@@ -124,15 +124,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`
-     * (JavaScript we run per event) — 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

@@ -2,10 +2,17 @@
 /**
  * The one place a request is made and a response judged.
  *
- * viaSocket answers every call with the same envelope, and it can say "no" two ways: a non-2xx
- * status, or a 2xx whose body carries `success: false`. Callers should never have to remember
- * that, so both become a ViaSocketError here with the API's own message attached — that message
- * is almost always the explanation.
+ * The embed endpoints answer with one envelope, `{ success, data }`, and can say "no" two ways:
+ * a non-2xx status, or a 2xx whose body carries `success: false`. Callers should never have to
+ * remember that, so both become a ViaSocketError here with the API's own message attached —
+ * 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 }`), 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;
@@ -29,9 +36,16 @@ async function request(options) {
     catch {
         payload = text;
     }
-    const envelope = payload && typeof payload === 'object' ? payload : null;
+    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 message = envelope?.message || envelope?.error?.message || `viaSocket responded ${response.status} for ${options.method} ${options.url}`;
+        const raw = payload && typeof payload === 'object' ? payload : null;
+        const message = envelope?.message ||
+            envelope?.error?.message ||
+            raw?.message ||
+            raw?.error?.message ||
+            `viaSocket responded ${response.status} for ${options.method} ${options.url}`;
         throw new errors_js_1.ViaSocketError(message, { status: response.status, body: payload });
     }
     return (envelope ?? { success: true, data: payload });

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

@@ -56,8 +56,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`
-     * (JavaScript we run per event) — 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

@@ -120,15 +120,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`
-     * (JavaScript we run per event) — 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

@@ -1,10 +1,17 @@
 /**
  * The one place a request is made and a response judged.
  *
- * viaSocket answers every call with the same envelope, and it can say "no" two ways: a non-2xx
- * status, or a 2xx whose body carries `success: false`. Callers should never have to remember
- * that, so both become a ViaSocketError here with the API's own message attached — that message
- * is almost always the explanation.
+ * The embed endpoints answer with one envelope, `{ success, data }`, and can say "no" two ways:
+ * a non-2xx status, or a 2xx whose body carries `success: false`. Callers should never have to
+ * remember that, so both become a ViaSocketError here with the API's own message attached —
+ * 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 }`), 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

@@ -1,10 +1,17 @@
 /**
  * The one place a request is made and a response judged.
  *
- * viaSocket answers every call with the same envelope, and it can say "no" two ways: a non-2xx
- * status, or a 2xx whose body carries `success: false`. Callers should never have to remember
- * that, so both become a ViaSocketError here with the API's own message attached — that message
- * is almost always the explanation.
+ * The embed endpoints answer with one envelope, `{ success, data }`, and can say "no" two ways:
+ * a non-2xx status, or a 2xx whose body carries `success: false`. Callers should never have to
+ * remember that, so both become a ViaSocketError here with the API's own message attached —
+ * 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 }`), 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) {
@@ -26,9 +33,16 @@ export async function request(options) {
     catch {
         payload = text;
     }
-    const envelope = payload && typeof payload === 'object' ? payload : null;
+    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 message = envelope?.message || envelope?.error?.message || `viaSocket responded ${response.status} for ${options.method} ${options.url}`;
+        const raw = payload && typeof payload === 'object' ? payload : null;
+        const message = envelope?.message ||
+            envelope?.error?.message ||
+            raw?.message ||
+            raw?.error?.message ||
+            `viaSocket responded ${response.status} for ${options.method} ${options.url}`;
         throw new ViaSocketError(message, { status: response.status, body: payload });
     }
     return (envelope ?? { success: true, data: payload });

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'.
  */

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,12 +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;
-    /** JavaScript run on each event instead of a webhook. */
+    /**
+     * 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
+     * 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>;
 }
@@ -70,6 +81,7 @@ export interface SubscribeResult {
     meta: Record<string, unknown>;
 }
 export interface UpdateSubscriptionParams {
+    /** A new script to run per event. Same rules as `SubscribeParams.code`. */
     code?: string;
     meta?: Record<string, unknown>;
 }

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "viasocket-apps",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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", "integrations", "oauth", "api", "webhooks", "slack", "github", "google-sheets"],
+  "keywords": [
+    "viasocket",
+    "integrations",
+    "oauth",
+    "api",
+    "webhooks",
+    "slack",
+    "github",
+    "google-sheets"
+  ],
   "license": "MIT",
   "author": "Walkover Web Solution",
   "homepage": "https://github.com/Walkover-Web-Solution/viasocket-apps#readme",
@@ -31,7 +40,10 @@
       "require": "./dist/cjs/browser.js"
     }
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/finish-build.mjs",