viasocket-apps 0.1.2 → 0.3.0

package/README.md

@@ -88,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 action_ids and trigger_ids 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_id>'], skipActionSelection: true })
 // Send authId to your backend, which enables the app and stores the script_id.
 ```
 
@@ -105,6 +107,9 @@ const { authId } = await connect({ embedToken, serviceId: 'rowbu58rc' })
 | `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; 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. |
+| `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 `null` or empty. No token. |
+| `viasocket.catalog.versions(serviceId)` | One app and every published action and trigger of it, as `{ service, actions, triggers }`. Each action has `action_id` and `action_version_id`, each trigger `trigger_id` and `trigger_version_id`, named as the calls take them: the version id for `runAction`, `listOptions` and `subscribe`; the other for `connect`, automations and the prebuilt UI. `input_schema` is the form schema. `null` for an unknown 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. |
 

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/scriK4LFg2kc'
+};
+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,79 @@ 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
+            }));
+        },
+        /**
+         * One app and every published action and trigger of it, as `{ service, actions, triggers }`.
+         * Each action carries `action_id` and `action_version_id`, each trigger `trigger_id` and
+         * `trigger_version_id` — named as the calls take them: the version id for `runAction`,
+         * `listOptions` and `subscribe`; the other for `connect`, automations and the prebuilt UI.
+         * `input_schema` is the field schema a form is rendered from. `null` for an unknown service id
+         * (the API answers 200 with an empty service); empty arrays 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
+            });
+            // No `success` key, so the body arrives whole as `data`; tolerate an envelope anyway.
+            const body = (data && 'service' in data ? data : data?.data) ?? {};
+            const service = body.service;
+            if (!service?.name)
+                return null;
+            return {
+                service,
+                actions: Array.isArray(body.actions) ? body.actions : [],
+                triggers: Array.isArray(body.triggers) ? body.triggers : []
+            };
+        }
+    };
     /** Everything that is done for one of your end users. */
     user(uniqueIdentifier) {
         return new UserScope(this, required('uniqueIdentifier', uniqueIdentifier));

package/dist/esm/browser.d.ts

@@ -27,9 +27,22 @@ 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 `action_id`s and `trigger_id`s this product uses (listed under each one in the app's
+     * document and in `catalog.versions()`). The popup then asks only for their scopes. Omit to
+     * offer every action. Never a version id.
+     */
+    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 +52,7 @@ export interface ConnectResult {
 }
 declare global {
     interface Window {
-        openViasocketConnection?: (embedToken: string, serviceId: string) => void;
+        openViasocketConnection?: (embedToken: string, serviceId: string, options?: ConnectScriptOptions) => void;
     }
 }
 /**
@@ -54,3 +67,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,30 @@ 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[]>;
+        /**
+         * One app and every published action and trigger of it, as `{ service, actions, triggers }`.
+         * Each action carries `action_id` and `action_version_id`, each trigger `trigger_id` and
+         * `trigger_version_id` — named as the calls take them: the version id for `runAction`,
+         * `listOptions` and `subscribe`; the other for `connect`, automations and the prebuilt UI.
+         * `input_schema` is the field schema a form is rendered from. `null` for an unknown service id
+         * (the API answers 200 with an empty service); empty arrays for an app with nothing published.
+         * Cache it per app; ids are stable and schemas change rarely.
+         */
+        versions: (serviceId: string) => Promise<CatalogVersions | null>;
+    };
     /** Everything that is done for one of your end users. */
     user(uniqueIdentifier: string): UserScope;
     /**

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/scriK4LFg2kc'
+};
+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,79 @@ 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
+            }));
+        },
+        /**
+         * One app and every published action and trigger of it, as `{ service, actions, triggers }`.
+         * Each action carries `action_id` and `action_version_id`, each trigger `trigger_id` and
+         * `trigger_version_id` — named as the calls take them: the version id for `runAction`,
+         * `listOptions` and `subscribe`; the other for `connect`, automations and the prebuilt UI.
+         * `input_schema` is the field schema a form is rendered from. `null` for an unknown service id
+         * (the API answers 200 with an empty service); empty arrays 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
+            });
+            // No `success` key, so the body arrives whole as `data`; tolerate an envelope anyway.
+            const body = (data && 'service' in data ? data : data?.data) ?? {};
+            const service = body.service;
+            if (!service?.name)
+                return null;
+            return {
+                service,
+                actions: Array.isArray(body.actions) ? body.actions : [],
+                triggers: Array.isArray(body.triggers) ? body.triggers : []
+            };
+        }
+    };
     /** Everything that is done for one of your end users. */
     user(uniqueIdentifier) {
         return new UserScope(this, required('uniqueIdentifier', uniqueIdentifier));

package/dist/esm/index.d.ts

@@ -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, CatalogAction, CatalogService, CatalogTrigger, CatalogVersion, CatalogVersions, EnableResult, Envelope, Flow, FlowStatus, ListAppsParams, ListOptionsParams, ListOptionsResult, Option, SubscribeParams, SubscribeResult, UpdateSubscriptionParams, ViaSocketOptions } from './types.js';

package/dist/esm/types.d.ts

@@ -98,9 +98,83 @@ 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;
+}
+/** The app, once, at the top of `catalog.versions()`. */
+export interface CatalogService {
+    service_id: string;
+    /** The display name. The API sends `null` for an unknown id; `versions()` then returns `null` instead of a catalog. */
+    name: string;
+    description: string | null;
+    icon_url: string | null;
+    /** `Auth2.0`, `apikey`, `NoAuth`, … Informational: connect handles it. */
+    auth_type: string | null;
+    /** `false` for an app without sign-in: no connect button, and `'NoAuth'` wherever a call takes an `authId`. */
+    requires_auth: boolean;
+}
+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.
+     */
+    input_schema: Record<string, unknown>;
+    /** A real response of the action, or a real event payload of the trigger. */
+    sample_output?: unknown;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+/** One published action, its two ids named as the calls take them. */
+export interface CatalogAction extends CatalogEventBase {
+    /**
+     * The action’s own id: what `connect`’s `actions`, an automation step’s `action_id` and the
+     * prebuilt UI’s `open: { actionId }` take. Looks like the version id and is not interchangeable with it.
+     */
+    action_id: string;
+    /** What `runAction` and `listOptions` take — and only those. */
+    action_version_id: string;
+}
+/** One published trigger, its two ids named as the calls take them. */
+export interface CatalogTrigger extends CatalogEventBase {
+    /**
+     * The trigger’s own id: what `connect`’s `actions`, an automation’s `trigger_id` and the prebuilt
+     * UI’s `open: { triggerId }` take. Looks like the version id and is not interchangeable with it.
+     */
+    trigger_id: string;
+    /** What `subscribe` and `listOptions` take — and only those. */
+    trigger_version_id: string;
+    /** Not reliable yet: the API answers `true` for every trigger. */
+    polled?: boolean | null;
+}
+/** @deprecated The catalog no longer returns rows of one shape; use `CatalogAction` and `CatalogTrigger`. */
+export type CatalogVersion = CatalogAction | CatalogTrigger;
+/** What `catalog.versions()` returns for a known app. */
+export interface CatalogVersions {
+    service: CatalogService;
+    actions: CatalogAction[];
+    triggers: CatalogTrigger[];
+}
 export interface Envelope<T = unknown> {
     success: boolean;
     message?: string;
     data: T;
     isCached?: boolean;
 }
+export {};

package/package.json

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