viasocket-apps 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Walkover Web Solution
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# viasocket-apps
+
+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 — with the OAuth, token refresh, per-app request shapes, polling and retries handled for
+you.
+
+Zero dependencies. Node 20+, Bun, Deno and edge runtimes.
+
+```sh
+npm install viasocket-apps
+```
+
+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.
+
+## Server
+
+```js
+import { ViaSocket } from 'viasocket-apps'
+
+const viasocket = new ViaSocket({
+  orgId: process.env.VIASOCKET_ORG_ID,
+  projectId: process.env.VIASOCKET_PROJECT_ID,
+  secret: process.env.VIASOCKET_EMBED_SECRET // server-side only
+})
+
+// Everything is done for one of your end users, identified by an id you choose.
+const user = viasocket.user('user_123')
+
+// 1. Your frontend needs a token to open the connect popup.
+const embedToken = await user.token()
+
+// 2. After the popup posts back an auth_id: enable the app, once, to run actions.
+const scriptId = (await user.findEnabled(serviceId)) ?? (await user.enable(serviceId, authId)).scriptId
+
+// 3. Fill a dropdown with the user's real data.
+const { options } = await user.listOptions(actionVersionId, {
+  fieldKey: 'spreadsheet_Id',
+  authId,
+  existingFields: {}
+})
+
+// 4. Run an action. No token — the script_id is the credential.
+const result = await viasocket.runAction(scriptId, actionVersionId, {
+  spreadsheet_Id: options[0].value,
+  grid_Id: '0',
+  column_key: true
+})
+
+// 5. Or subscribe to an event. Needs only the connection, not enable().
+const subscription = await user.subscribe(triggerVersionId, {
+  authId,
+  inputData: { channel_id: ['C08SXCV3J85'] },
+  webhook: 'https://your-app.com/webhooks/viasocket',
+  meta: { userId: 'user_123' }
+})
+```
+
+## Browser
+
+```js
+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' })
+// Send authId to your backend, which enables the app and stores the script_id.
+```
+
+`connect()` rejects with a `ViaSocketConnectError` whose `code` is `'closed'` (the user gave up),
+`'rejected'` (the app said no) or `'script'` (the connect script did not load).
+
+## Methods
+
+| Call | What it does |
+| --- | --- |
+| `viasocket.user(id)` | Scope every call below to one end user. |
+| `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. |
+| `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. |
+| `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. |
+| `user.revokeConnection(authId)` | Disconnect an app. Disable its flows first. |
+| `signEmbedToken({ orgId, projectId, uniqueIdentifier, secret })` | The signing step on its own, if you want it without a client. |
+
+Every failure — a non-2xx status or a body with `success: false` — throws a `ViaSocketError`
+carrying the API's own `message`, the HTTP `status`, and the parsed `body`.
+
+## Rules the API holds you to
+
+1. **The secret and the token stay on the server.** The frontend gets a token per popup, nothing more.
+2. **A `scriptId` is a credential.** Anyone holding it can run that app as that user.
+3. **Ids are fetched, never guessed.** Spreadsheet ids, channel ids, repository ids all come from `listOptions`.
+4. **`existingFields` is not optional when a field depends on another.** Options are scoped by it.
+5. **One `uniqueIdentifier` per end user, forever.** Connections and subscriptions are isolated by it.
+6. **Enable only for actions, and check `findEnabled` first.** Subscriptions need just the connection.
+
+## Environments
+
+Defaults target production: `https://flow-api.viasocket.com` for the API and
+`https://flow.sokt.io` for running actions. Pass `apiBaseUrl` / `runBaseUrl` to point elsewhere,
+and `scriptUrl` to `connect()` for a non-production connect script.
+
+## License
+
+MIT

package/dist/cjs/browser.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * The browser half: opening the app's own consent screen and getting the connection back.
+ *
+ *   import { connect } from 'viasocket-apps/browser'
+ *   const { authId } = await connect({ embedToken, serviceId })
+ *
+ * It wraps viaSocket's standalone connect script — the popup, the postMessage handshake, the
+ * three message types — behind one promise. Nothing here touches the signing secret: the
+ * embedToken comes from your backend, already signed for this end user.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViaSocketConnectError = void 0;
+exports.loadConnectScript = loadConnectScript;
+exports.connect = connect;
+const DEFAULT_SCRIPT_URL = 'https://embed.viasocket.com/prod-connectcomponent.js';
+const SCRIPT_ID = 'viasocket-connect-script';
+class ViaSocketConnectError extends Error {
+    code;
+    serviceId;
+    constructor(code, serviceId, message) {
+        super(message);
+        this.name = 'ViaSocketConnectError';
+        this.code = code;
+        this.serviceId = serviceId;
+    }
+}
+exports.ViaSocketConnectError = ViaSocketConnectError;
+/** Loaded once per page, however many apps get connected. */
+let scriptPromise = null;
+/**
+ * Loads the connect script ahead of the click, so the popup opens without a delay. Optional —
+ * `connect()` loads it on demand.
+ */
+function loadConnectScript(scriptUrl = DEFAULT_SCRIPT_URL) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return Promise.reject(new ViaSocketConnectError('unavailable', '', 'connect() only runs in a browser'));
+    }
+    if (typeof window.openViasocketConnection === 'function')
+        return Promise.resolve();
+    if (scriptPromise)
+        return scriptPromise;
+    scriptPromise = new Promise((resolve, reject) => {
+        const fail = () => {
+            scriptPromise = null;
+            document.getElementById(SCRIPT_ID)?.remove();
+            reject(new ViaSocketConnectError('script', '', `Could not load the viaSocket connect script from ${scriptUrl}`));
+        };
+        const existing = document.getElementById(SCRIPT_ID);
+        const script = existing ?? document.createElement('script');
+        script.addEventListener('load', () => resolve(), { once: true });
+        script.addEventListener('error', fail, { once: true });
+        if (!existing) {
+            script.id = SCRIPT_ID;
+            script.src = scriptUrl;
+            document.body.appendChild(script);
+        }
+    });
+    return scriptPromise;
+}
+/**
+ * Opens the consent popup for one app and resolves with the connection it creates.
+ *
+ * Rejects with a ViaSocketConnectError whose `code` says why: 'closed' if the user gave up,
+ * 'rejected' if the app said no, 'script' if the connect script could not load.
+ */
+async function connect(options) {
+    const serviceId = options?.serviceId;
+    if (!options?.embedToken)
+        throw new ViaSocketConnectError('unavailable', serviceId ?? '', 'connect: embedToken is required');
+    if (!serviceId)
+        throw new ViaSocketConnectError('unavailable', '', 'connect: serviceId is required');
+    await loadConnectScript(options.scriptUrl);
+    const open = window.openViasocketConnection;
+    if (typeof open !== 'function') {
+        throw new ViaSocketConnectError('script', serviceId, 'The connect script loaded but did not expose openViasocketConnection()');
+    }
+    return new Promise((resolve, reject) => {
+        const onMessage = (event) => {
+            const payload = event?.data;
+            if (!payload || typeof payload.type !== 'string' || !payload.type.startsWith('viasocket_connection'))
+                return;
+            // Two apps can be connecting in one page; only this app's messages are ours.
+            if (payload.serviceId && payload.serviceId !== serviceId)
+                return;
+            window.removeEventListener('message', onMessage);
+            if (payload.type === 'viasocket_connection_success') {
+                const connection = (payload.data ?? {});
+                const authId = typeof connection.id === 'string' ? connection.id : '';
+                if (!authId) {
+                    reject(new ViaSocketConnectError('rejected', serviceId, 'The connection succeeded but carried no id'));
+                    return;
+                }
+                resolve({ authId, serviceId, connection });
+            }
+            else if (payload.type === 'viasocket_connection_error') {
+                reject(new ViaSocketConnectError('rejected', serviceId, payload.error?.message || 'The app rejected the connection'));
+            }
+            else if (payload.type === 'viasocket_connection_closed') {
+                reject(new ViaSocketConnectError('closed', serviceId, 'The popup was closed before the connection finished'));
+            }
+        };
+        window.addEventListener('message', onMessage);
+        open(options.embedToken, serviceId);
+    });
+}

package/dist/cjs/client.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * The client. One `ViaSocket` per deployment, one `UserScope` per end user.
+ *
+ * The split mirrors the API's own model: every call except running an action is made *for* a
+ * specific end user (the `unique_identifier` in the token), while running an action needs no
+ * token at all — the `script_id` is the credential. Putting `runAction` on the root client and
+ * everything else behind `user(id)` makes that distinction structural rather than something a
+ * reader has to remember.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserScope = exports.ViaSocket = void 0;
+const errors_js_1 = require("./errors.js");
+const http_js_1 = require("./http.js");
+const token_js_1 = require("./token.js");
+const DEFAULT_API_BASE_URL = 'https://flow-api.viasocket.com';
+const DEFAULT_RUN_BASE_URL = 'https://flow.sokt.io';
+function required(name, value) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new errors_js_1.ViaSocketError(`${name} is required`, { status: null });
+    return value;
+}
+const trimSlash = (url) => url.replace(/\/+$/, '');
+class ViaSocket {
+    orgId;
+    projectId;
+    apiBaseUrl;
+    runBaseUrl;
+    secret;
+    /** @internal */
+    transport;
+    constructor(options) {
+        this.orgId = required('orgId', options?.orgId);
+        this.projectId = required('projectId', options?.projectId);
+        this.secret = required('secret', options?.secret);
+        this.apiBaseUrl = trimSlash(options.apiBaseUrl || DEFAULT_API_BASE_URL);
+        this.runBaseUrl = trimSlash(options.runBaseUrl || DEFAULT_RUN_BASE_URL);
+        const transport = options.fetch ?? globalThis.fetch;
+        if (typeof transport !== 'function') {
+            throw new errors_js_1.ViaSocketError('No fetch available. Use Node 20+, or pass `fetch` in the options.', { status: null });
+        }
+        // Bound so a bare `fetch` reference still has the right `this` on runtimes that care.
+        this.transport = options.fetch ? transport : transport.bind(globalThis);
+    }
+    /** Everything that is done for one of your end users. */
+    user(uniqueIdentifier) {
+        return new UserScope(this, required('uniqueIdentifier', uniqueIdentifier));
+    }
+    /**
+     * A signed embed token for one end user — what the connect popup on your frontend needs.
+     * Sign on demand per request; there is nothing to gain from caching it in the browser.
+     */
+    tokenFor(uniqueIdentifier) {
+        return (0, token_js_1.signEmbedToken)({
+            orgId: this.orgId,
+            projectId: this.projectId,
+            uniqueIdentifier: required('uniqueIdentifier', uniqueIdentifier),
+            secret: this.secret
+        });
+    }
+    /**
+     * Runs one action. No token: the script_id from `user.enable()` is the credential, which is
+     * exactly why this call belongs on your server.
+     */
+    async runAction(scriptId, actionVersionId, inputData) {
+        const payload = await (0, http_js_1.request)({
+            method: 'POST',
+            url: `${this.runBaseUrl}/func/${required('scriptId', scriptId)}`,
+            body: JSON.stringify({ action_version_id: required('actionVersionId', actionVersionId), inputData: inputData ?? {} }),
+            fetchImpl: this.transport
+        });
+        return payload.data;
+    }
+}
+exports.ViaSocket = ViaSocket;
+/**
+ * Calls made on behalf of one end user. Obtained from `viasocket.user(id)`.
+ *
+ * The token is signed once per scope and reused: it carries no expiry, so there is nothing to
+ * refresh, and re-signing per call would only add work.
+ */
+class UserScope {
+    client;
+    uniqueIdentifier;
+    tokenPromise;
+    constructor(client, uniqueIdentifier) {
+        this.client = client;
+        this.uniqueIdentifier = uniqueIdentifier;
+    }
+    /** The signed embed token for this user. */
+    token() {
+        this.tokenPromise ??= this.client.tokenFor(this.uniqueIdentifier);
+        return this.tokenPromise;
+    }
+    async call(method, path, body) {
+        return (0, http_js_1.request)({
+            method,
+            url: `${this.client.apiBaseUrl}${path}`,
+            token: await this.token(),
+            body: body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body),
+            fetchImpl: this.client.transport
+        });
+    }
+    /**
+     * Turns a connection into a script_id you can run actions with. Needed only for actions —
+     * subscribing to a trigger takes the auth_id alone. Do it once per connection; see
+     * `findEnabled()` before calling it again.
+     */
+    async enable(serviceId, authId) {
+        const { data } = await this.call('POST', `/embed/enable/${required('serviceId', serviceId)}/${required('authId', authId)}`, '');
+        return { scriptId: data.script_id, webhookUrl: data.webhook_url, serviceId: data.service_id, authId: data.auth_id };
+    }
+    /**
+     * The values one field accepts, scoped by what the user has already chosen.
+     *
+     * Handles both response shapes the endpoint uses — a plain array, or `{ data, offset }` on
+     * fields that paginate — so the caller always gets `{ options, offset }`.
+     */
+    async listOptions(actionVersionId, params) {
+        const { data } = await this.call('POST', `/embed/list-options/${required('actionVersionId', actionVersionId)}`, {
+            fieldKey: required('fieldKey', params?.fieldKey),
+            auth_id: required('authId', params?.authId),
+            existingFields: params?.existingFields ?? {}
+        });
+        if (Array.isArray(data))
+            return { options: data, offset: null };
+        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.
+     */
+    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 });
+        }
+        const body = {
+            auth_id: required('authId', params.authId),
+            inputData: params.inputData ?? {},
+            meta: params.meta ?? {}
+        };
+        if (params.webhook)
+            body.webhook = params.webhook;
+        if (params.code)
+            body.code = params.code;
+        const { data } = await this.call('POST', `/embed/subscribe-event/${required('triggerVersionId', triggerVersionId)}`, body);
+        return {
+            scriptId: data.script_id,
+            hookUrl: data.inputData?.hookUrl ?? '',
+            title: data.title,
+            authId: data.auth_id,
+            inputData: data.inputData ?? {},
+            meta: data.meta ?? {}
+        };
+    }
+    /** Changes a live subscription in place. The script_id does not change. */
+    async updateSubscription(subscriptionScriptId, params) {
+        const { data } = await this.call('PUT', `/embed/update-subscribed-event/${required('subscriptionScriptId', subscriptionScriptId)}`, params ?? {});
+        return {
+            scriptId: data.script_id,
+            hookUrl: data.inputData?.hookUrl ?? '',
+            title: data.title,
+            authId: data.auth_id,
+            inputData: data.inputData ?? {},
+            meta: data.meta ?? {}
+        };
+    }
+    /** Every flow this user has: one per enabled app, one per trigger subscription. */
+    async listFlows() {
+        const { data } = await this.call('GET', `/projects/${this.client.projectId}/integrations`);
+        return (data?.flows ?? []).map((flow) => ({
+            id: flow.id,
+            title: flow.title,
+            status: flow.status,
+            webhook: flow.webhook,
+            description: flow.description ?? '',
+            authId: flow.auth_id,
+            serviceId: flow.service_id
+        }));
+    }
+    /**
+     * The script_id of an app this user already enabled, or null. Call it before `enable()` —
+     * enabling twice leaves you with two script_ids for one app.
+     */
+    async findEnabled(serviceId) {
+        const flows = await this.listFlows();
+        return flows.find((flow) => flow.serviceId === required('serviceId', serviceId) && flow.status === 'active')?.id ?? null;
+    }
+    /** Turns a flow off (0) or back on (1): an enabled app, or a trigger subscription. */
+    async setFlowStatus(scriptId, status) {
+        const { data } = await this.call('PUT', `/embed/updatestatus/${required('scriptId', scriptId)}?status=${status}`);
+        // The response is the whole flow record; nothing else in it is anything a caller acts on.
+        return { id: data.id, status: String(data.status) };
+    }
+    disableFlow(scriptId) {
+        return this.setFlowStatus(scriptId, 0);
+    }
+    enableFlow(scriptId) {
+        return this.setFlowStatus(scriptId, 1);
+    }
+    /**
+     * Every app this user has connected. Returned as the API sends it: the shape of each entry
+     * is not yet documented, so nothing is mapped or dropped here.
+     */
+    async listConnections() {
+        const { data } = await this.call('GET', '/embed/authentications');
+        return Array.isArray(data) ? data : [];
+    }
+    /** Disconnects an app. Disable the flows built on it first, or they stop working. */
+    async revokeConnection(authId) {
+        await this.call('DELETE', `/embed/authentications/revoke/${required('authId', authId)}`);
+    }
+}
+exports.UserScope = UserScope;

package/dist/cjs/errors.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViaSocketError = void 0;
+/**
+ * Thrown for any call that did not succeed — a non-2xx status, or a 2xx whose body says
+ * `success: false`. Both carry the message the API gave, because that message is almost
+ * always the explanation ("existingFields missing spreadsheet_Id", "invalid token").
+ */
+class ViaSocketError extends Error {
+    /** HTTP status, or null when the request never got a response. */
+    status;
+    /** The parsed response body, when there was one. */
+    body;
+    constructor(message, options) {
+        super(message);
+        this.name = 'ViaSocketError';
+        this.status = options.status;
+        this.body = options.body;
+    }
+}
+exports.ViaSocketError = ViaSocketError;

package/dist/cjs/http.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.request = request;
+const errors_js_1 = require("./errors.js");
+async function request(options) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (options.token)
+        headers.authorization = options.token;
+    let response;
+    try {
+        response = await options.fetchImpl(options.url, { method: options.method, headers, body: options.body });
+    }
+    catch (error) {
+        throw new errors_js_1.ViaSocketError(`Request to ${options.url} failed: ${error?.message || 'network error'}`, { status: null });
+    }
+    const text = await response.text();
+    let payload = null;
+    try {
+        payload = text ? JSON.parse(text) : null;
+    }
+    catch {
+        payload = text;
+    }
+    const envelope = payload && typeof payload === 'object' ? payload : null;
+    if (!response.ok || envelope?.success === false) {
+        const message = envelope?.message || envelope?.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

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * viasocket-apps — server-side client for the viaSocket Apps API.
+ *
+ *   import { ViaSocket } from 'viasocket-apps'
+ *
+ *   const viasocket = new ViaSocket({ orgId, projectId, secret: process.env.VIASOCKET_EMBED_SECRET })
+ *   const user = viasocket.user(endUserId)
+ *
+ *   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 })
+ *
+ * The browser half — opening the connect popup — lives at 'viasocket-apps/browser'.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signEmbedToken = exports.ViaSocketError = exports.UserScope = exports.ViaSocket = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "ViaSocket", { enumerable: true, get: function () { return client_js_1.ViaSocket; } });
+Object.defineProperty(exports, "UserScope", { enumerable: true, get: function () { return client_js_1.UserScope; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "ViaSocketError", { enumerable: true, get: function () { return errors_js_1.ViaSocketError; } });
+var token_js_1 = require("./token.js");
+Object.defineProperty(exports, "signEmbedToken", { enumerable: true, get: function () { return token_js_1.signEmbedToken; } });

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/token.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * The embed token: an HS256 JWT of { org_id, project_id, unique_identifier }, signed with the
+ * org secret.
+ *
+ * Implemented on WebCrypto rather than a JWT library so the package has no dependencies and
+ * runs unchanged on Node 20+, Bun, Deno and edge runtimes. The payload is exactly the three
+ * claims the platform reads, in that order — nothing is added, because the token's only job is
+ * to say which end user a call is for.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signEmbedToken = signEmbedToken;
+const errors_js_1 = require("./errors.js");
+const encoder = new TextEncoder();
+/** Standard base64url: the URL-safe alphabet, no padding. */
+function base64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function encodeSegment(value) {
+    return base64Url(encoder.encode(JSON.stringify(value)));
+}
+async function signEmbedToken(input) {
+    for (const [name, value] of Object.entries(input)) {
+        if (typeof value !== 'string' || !value) {
+            throw new errors_js_1.ViaSocketError(`signEmbedToken: ${name} is required`, { status: null });
+        }
+    }
+    const header = encodeSegment({ alg: 'HS256', typ: 'JWT' });
+    const payload = encodeSegment({
+        org_id: input.orgId,
+        project_id: input.projectId,
+        unique_identifier: input.uniqueIdentifier
+    });
+    const signingInput = `${header}.${payload}`;
+    const key = await crypto.subtle.importKey('raw', encoder.encode(input.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(signingInput));
+    return `${signingInput}.${base64Url(new Uint8Array(signature))}`;
+}

package/dist/cjs/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Public types. Everything the API returns in snake_case is mapped to camelCase here, so the
+ * shape a caller sees is the shape a JavaScript codebase expects — and so that if a field is
+ * ever renamed upstream, it is renamed in one place.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/browser.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The browser half: opening the app's own consent screen and getting the connection back.
+ *
+ *   import { connect } from 'viasocket-apps/browser'
+ *   const { authId } = await connect({ embedToken, serviceId })
+ *
+ * It wraps viaSocket's standalone connect script — the popup, the postMessage handshake, the
+ * three message types — behind one promise. Nothing here touches the signing secret: the
+ * embedToken comes from your backend, already signed for this end user.
+ */
+export type ConnectErrorCode = 
+/** The user closed the popup before finishing. Nothing was created. */
+'closed'
+/** The app refused the authorisation. */
+ | 'rejected'
+/** The connect script could not be loaded. */
+ | 'script'
+/** Not running in a browser, or the popup could not be opened. */
+ | 'unavailable';
+export declare class ViaSocketConnectError extends Error {
+    readonly code: ConnectErrorCode;
+    readonly serviceId: string;
+    constructor(code: ConnectErrorCode, serviceId: string, message: string);
+}
+export interface ConnectOptions {
+    /** Signed on your backend for the current end user — see `viasocket.user(id).token()`. */
+    embedToken: string;
+    /** The app to connect. Its service_id is shown on every app in the Apps API reference. */
+    serviceId: string;
+    /** Where the connect script is served from. Only override for a non-production environment. */
+    scriptUrl?: string;
+}
+export interface ConnectResult {
+    /** The connection. Every later call for this app takes it as auth_id. */
+    authId: string;
+    serviceId: string;
+    /** The full connection record the popup posted back. */
+    connection: Record<string, unknown>;
+}
+declare global {
+    interface Window {
+        openViasocketConnection?: (embedToken: string, serviceId: string) => void;
+    }
+}
+/**
+ * Loads the connect script ahead of the click, so the popup opens without a delay. Optional —
+ * `connect()` loads it on demand.
+ */
+export declare function loadConnectScript(scriptUrl?: string): Promise<void>;
+/**
+ * Opens the consent popup for one app and resolves with the connection it creates.
+ *
+ * Rejects with a ViaSocketConnectError whose `code` says why: 'closed' if the user gave up,
+ * 'rejected' if the app said no, 'script' if the connect script could not load.
+ */
+export declare function connect(options: ConnectOptions): Promise<ConnectResult>;