viasocket-apps 0.1.0 → 0.1.1

package/README.md

@@ -83,6 +83,23 @@ const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc' })
 | `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.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`:
+
+```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 }
+  `
+})
+```
 | `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

@@ -127,8 +127,9 @@ class UserScope {
         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. 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.
      */
     async subscribe(triggerVersionId, params) {
         if (!params?.webhook === !params?.code) {

package/dist/cjs/http.js

@@ -2,10 +2,16 @@
 /**
  * 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 }`). 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.request = request;
@@ -29,9 +35,15 @@ async function request(options) {
     catch {
         payload = text;
     }
-    const envelope = payload && typeof payload === 'object' ? payload : null;
+    const isEnvelope = payload !== null && typeof payload === 'object' && typeof payload.success === 'boolean';
+    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/esm/client.d.ts

@@ -56,8 +56,9 @@ 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. 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.
      */
     subscribe(triggerVersionId: string, params: SubscribeParams): Promise<SubscribeResult>;
     /** Changes a live subscription in place. The script_id does not change. */

package/dist/esm/client.js

@@ -123,8 +123,9 @@ export class UserScope {
         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. 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.
      */
     async subscribe(triggerVersionId, params) {
         if (!params?.webhook === !params?.code) {

package/dist/esm/http.d.ts

@@ -1,10 +1,16 @@
 /**
  * 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 }`). 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.
  */
 import type { Envelope } from './types.js';
 export interface RequestOptions {

package/dist/esm/http.js

@@ -1,10 +1,16 @@
 /**
  * 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 }`). 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.
  */
 import { ViaSocketError } from './errors.js';
 export async function request(options) {
@@ -26,9 +32,15 @@ export async function request(options) {
     catch {
         payload = text;
     }
-    const envelope = payload && typeof payload === 'object' ? payload : null;
+    const isEnvelope = payload !== null && typeof payload === 'object' && typeof payload.success === 'boolean';
+    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/types.d.ts

@@ -54,7 +54,14 @@ export interface SubscribeParams {
     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. */
+    /**
+     * Instead of a webhook: a script we run on viaSocket's servers each time the event fires.
+     *
+     * 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.
+     */
     code?: string;
     /** Anything of yours; handed back with every delivery. */
     meta?: Record<string, unknown>;
@@ -70,6 +77,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.1",
   "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",