@scalar/workspace-store 0.51.2 → 0.52.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @scalar/workspace-store
 
+## 0.52.0
+
+### Minor Changes
+
+- [#9313](https://github.com/scalar/scalar/pull/9313): feat: add AsyncAPI connection URL builder and server list helpers
+
+### Patch Changes
+
+- [#9334](https://github.com/scalar/scalar/pull/9334): Add analytics events for document save and registry sync (pull/push) actions
+- [#9333](https://github.com/scalar/scalar/pull/9333): feat: respect the `x-order` extension when building schema examples
+
 ## 0.51.2
 
 ## 0.51.1

package/dist/channel-example/build-connection-url.d.ts

@@ -0,0 +1,42 @@
+import type { AsyncApiChannelObject, AsyncApiOperationObject, AsyncApiServerObject, AsyncApiWsBindingObject } from '@scalar/types/asyncapi/3.1';
+/** AsyncAPI server protocols supported for WebSocket connections in the API client MVP. */
+export declare const ASYNCAPI_WEBSOCKET_PROTOCOLS: readonly ["ws", "wss"];
+export type AsyncApiWebSocketProtocol = (typeof ASYNCAPI_WEBSOCKET_PROTOCOLS)[number];
+export type BuildConnectionUrlInput = {
+    server: AsyncApiServerObject;
+    channel: AsyncApiChannelObject;
+    operation?: AsyncApiOperationObject | null;
+    pathParameters?: Record<string, string>;
+    queryParameters?: Record<string, string>;
+    environmentVariables?: Record<string, string> | ((key: string) => string | null);
+};
+/**
+ * Extracts default values of variables defined on an AsyncAPI Server Object.
+ */
+export declare const getAsyncApiServerVariables: (server: AsyncApiServerObject | null) => Record<string, string>;
+/** Maps AsyncAPI `server.protocol` to a URL scheme (MVP: ws and wss). */
+export declare const getUrlSchemeFromProtocol: (protocol: string) => string;
+export declare const isWebSocketProtocol: (protocol: string) => protocol is AsyncApiWebSocketProtocol;
+/**
+ * Builds the server base URL: scheme, host, and optional pathname (no channel address).
+ */
+export declare const buildAsyncApiServerBaseUrl: (server: AsyncApiServerObject, environmentVariables?: BuildConnectionUrlInput["environmentVariables"]) => string;
+/** Merges channel and operation WebSocket bindings; operation fields override channel. */
+export declare const mergeWsBindings: (channel: AsyncApiChannelObject, operation?: AsyncApiOperationObject | null) => AsyncApiWsBindingObject | undefined;
+/**
+ * Builds handshake query parameters from merged `bindings.ws.query` schema defaults,
+ * then applies explicit overrides.
+ */
+export declare const buildWsQueryParams: (wsBinding: AsyncApiWsBindingObject | undefined, queryParameters?: Record<string, string>) => URLSearchParams;
+/**
+ * Builds a WebSocket connection URL from a resolved server, channel, and optional operation.
+ *
+ * Composition (AsyncAPI 3.x):
+ * 1. `server.protocol` → URL scheme
+ * 2. `server.host` (+ variables and environment substitution)
+ * 3. Optional `server.pathname`
+ * 4. Channel `address` (+ path parameter substitution)
+ * 5. Query string from merged `bindings.ws.query` (channel + operation) with schema defaults
+ */
+export declare const buildConnectionUrl: ({ server, channel, operation, pathParameters, queryParameters, environmentVariables, }: BuildConnectionUrlInput) => string;
+//# sourceMappingURL=build-connection-url.d.ts.map

package/dist/channel-example/build-connection-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-connection-url.d.ts","sourceRoot":"","sources":["../../src/channel-example/build-connection-url.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACxB,MAAM,4BAA4B,CAAA;AAInC,2FAA2F;AAC3F,eAAO,MAAM,4BAA4B,wBAAyB,CAAA;AAElE,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAA;AAErF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,oBAAoB,CAAA;IAC5B,OAAO,EAAE,qBAAqB,CAAA;IAC9B,SAAS,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAA;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC,CAAA;CACjF,CAAA;AAQD;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,oBAAoB,GAAG,IAAI,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAYrG,CAAA;AAoBD,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,GAAI,UAAU,MAAM,KAAG,MAAuC,CAAA;AAEnG,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,QAAQ,IAAI,yBAC0B,CAAA;AAE7F;;GAEG;AACH,eAAO,MAAM,0BAA0B,GACrC,QAAQ,oBAAoB,EAC5B,uBAAuB,uBAAuB,CAAC,sBAAsB,CAAC,KACrE,MAYF,CAAA;AAaD,0FAA0F;AAC1F,eAAO,MAAM,eAAe,GAC1B,SAAS,qBAAqB,EAC9B,YAAY,uBAAuB,GAAG,IAAI,KACzC,uBAAuB,GAAG,SAa5B,CAAA;AAuFD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,WAAW,uBAAuB,GAAG,SAAS,EAC9C,kBAAkB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KACvC,eAmBF,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,wFAOhC,uBAAuB,KAAG,MAkB5B,CAAA"}

package/dist/channel-example/build-connection-url.js

@@ -0,0 +1,181 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+import { objectEntries } from '@scalar/helpers/object/object-entries';
+import { replaceEnvVariables, replacePathVariables } from '@scalar/helpers/regex/replace-variables';
+import { combineUrlAndPath, mergeUrls } from '@scalar/helpers/url/merge-urls';
+import { getResolvedRef } from '../helpers/get-resolved-ref.js';
+/** AsyncAPI server protocols supported for WebSocket connections in the API client MVP. */
+export const ASYNCAPI_WEBSOCKET_PROTOCOLS = ['ws', 'wss'];
+/**
+ * Extracts default values of variables defined on an AsyncAPI Server Object.
+ */
+export const getAsyncApiServerVariables = (server) => {
+    if (!server?.variables) {
+        return {};
+    }
+    return objectEntries(server.variables).reduce((acc, [name, variable]) => {
+        const resolved = getResolvedRef(variable);
+        if (resolved.default != null) {
+            acc[String(name)] = String(resolved.default);
+        }
+        return acc;
+    }, {});
+};
+const substituteTemplate = (template, options) => {
+    let result = template;
+    if (options.serverVariables) {
+        result = replacePathVariables(result, options.serverVariables);
+    }
+    if (options.environmentVariables) {
+        result = replaceEnvVariables(result, options.environmentVariables);
+    }
+    if (options.pathParameters) {
+        result = replacePathVariables(result, options.pathParameters);
+    }
+    return result;
+};
+/** Maps AsyncAPI `server.protocol` to a URL scheme (MVP: ws and wss). */
+export const getUrlSchemeFromProtocol = (protocol) => protocol.trim().toLowerCase();
+export const isWebSocketProtocol = (protocol) => ASYNCAPI_WEBSOCKET_PROTOCOLS.includes(protocol.trim().toLowerCase());
+/**
+ * Builds the server base URL: scheme, host, and optional pathname (no channel address).
+ */
+export const buildAsyncApiServerBaseUrl = (server, environmentVariables) => {
+    const serverVariables = getAsyncApiServerVariables(server);
+    const scheme = getUrlSchemeFromProtocol(server.protocol);
+    const host = substituteTemplate(server.host, { serverVariables, environmentVariables });
+    const origin = `${scheme}://${host}`;
+    if (!server.pathname) {
+        return origin;
+    }
+    const pathname = substituteTemplate(server.pathname, { serverVariables, environmentVariables });
+    return combineUrlAndPath(origin, pathname);
+};
+const resolveWsBinding = (bindings) => {
+    if (!bindings) {
+        return undefined;
+    }
+    const resolved = getResolvedRef(bindings);
+    return resolved.ws;
+};
+/** Merges channel and operation WebSocket bindings; operation fields override channel. */
+export const mergeWsBindings = (channel, operation) => {
+    const channelBinding = resolveWsBinding(channel.bindings);
+    const operationBinding = operation ? resolveWsBinding(operation.bindings) : undefined;
+    if (!channelBinding && !operationBinding) {
+        return undefined;
+    }
+    return {
+        ...channelBinding,
+        ...operationBinding,
+        query: mergeWsQuerySchemas(channelBinding?.query, operationBinding?.query),
+    };
+};
+const resolveWsQuerySchema = (query) => {
+    if (!query) {
+        return undefined;
+    }
+    const resolved = getResolvedRef(query);
+    if (resolved === true || resolved === false || !isObject(resolved)) {
+        return undefined;
+    }
+    return resolved;
+};
+const mergeWsQuerySchemas = (channelQuery, operationQuery) => {
+    const channelSchema = resolveWsQuerySchema(channelQuery);
+    const operationSchema = resolveWsQuerySchema(operationQuery);
+    if (!channelSchema && !operationSchema) {
+        return undefined;
+    }
+    if (!channelSchema) {
+        return operationQuery;
+    }
+    if (!operationSchema) {
+        return channelQuery;
+    }
+    const channelProperties = isObject(channelSchema.properties) ? channelSchema.properties : {};
+    const operationProperties = isObject(operationSchema.properties) ? operationSchema.properties : {};
+    return {
+        ...channelSchema,
+        ...operationSchema,
+        properties: {
+            ...channelProperties,
+            ...operationProperties,
+        },
+    };
+};
+const getDefaultValueFromPropertySchema = (propertySchema) => {
+    if (propertySchema === true || propertySchema === false || !isObject(propertySchema)) {
+        return undefined;
+    }
+    if ('default' in propertySchema && propertySchema.default !== undefined) {
+        return propertySchema.default;
+    }
+    if ('example' in propertySchema && propertySchema.example !== undefined) {
+        return propertySchema.example;
+    }
+    if ('enum' in propertySchema && Array.isArray(propertySchema.enum) && propertySchema.enum[0] !== undefined) {
+        return propertySchema.enum[0];
+    }
+    return undefined;
+};
+const appendQueryValue = (params, key, value) => {
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry) => appendQueryValue(params, key, entry));
+        return;
+    }
+    if (typeof value === 'object') {
+        params.append(key, JSON.stringify(value));
+        return;
+    }
+    params.append(key, String(value));
+};
+/**
+ * Builds handshake query parameters from merged `bindings.ws.query` schema defaults,
+ * then applies explicit overrides.
+ */
+export const buildWsQueryParams = (wsBinding, queryParameters) => {
+    const params = new URLSearchParams();
+    const querySchema = resolveWsQuerySchema(wsBinding?.query);
+    if (querySchema && isObject(querySchema.properties)) {
+        for (const [name, propertySchema] of objectEntries(querySchema.properties)) {
+            const defaultValue = getDefaultValueFromPropertySchema(propertySchema);
+            appendQueryValue(params, name, defaultValue);
+        }
+    }
+    if (queryParameters) {
+        for (const [name, value] of objectEntries(queryParameters)) {
+            params.delete(name);
+            appendQueryValue(params, name, value);
+        }
+    }
+    return params;
+};
+/**
+ * Builds a WebSocket connection URL from a resolved server, channel, and optional operation.
+ *
+ * Composition (AsyncAPI 3.x):
+ * 1. `server.protocol` → URL scheme
+ * 2. `server.host` (+ variables and environment substitution)
+ * 3. Optional `server.pathname`
+ * 4. Channel `address` (+ path parameter substitution)
+ * 5. Query string from merged `bindings.ws.query` (channel + operation) with schema defaults
+ */
+export const buildConnectionUrl = ({ server, channel, operation = null, pathParameters = {}, queryParameters = {}, environmentVariables, }) => {
+    const serverVariables = getAsyncApiServerVariables(server);
+    const baseUrl = buildAsyncApiServerBaseUrl(server, environmentVariables);
+    const address = channel.address;
+    if (address == null || address === '') {
+        const queryParams = buildWsQueryParams(mergeWsBindings(channel, operation), queryParameters);
+        return mergeUrls(baseUrl, '', queryParams, true);
+    }
+    const resolvedAddress = substituteTemplate(address, {
+        serverVariables,
+        environmentVariables,
+        pathParameters,
+    });
+    const queryParams = buildWsQueryParams(mergeWsBindings(channel, operation), queryParameters);
+    return mergeUrls(baseUrl, resolvedAddress, queryParams, true);
+};

package/dist/channel-example/index.d.ts

@@ -0,0 +1,5 @@
+export type { AsyncApiWebSocketProtocol, BuildConnectionUrlInput } from './build-connection-url.js';
+export { ASYNCAPI_WEBSOCKET_PROTOCOLS, buildAsyncApiServerBaseUrl, buildConnectionUrl, buildWsQueryParams, getAsyncApiServerVariables, getUrlSchemeFromProtocol, isWebSocketProtocol, mergeWsBindings, } from './build-connection-url.js';
+export type { AsyncApiServerEntry, AsyncApiServerListOptions } from './servers.js';
+export { getAsyncApiServers, getSelectedAsyncApiServer } from './servers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/channel-example/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/channel-example/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAChG,OAAO,EACL,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,GAChB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA;AAC/E,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA"}

package/dist/channel-example/index.js

@@ -0,0 +1,2 @@
+export { ASYNCAPI_WEBSOCKET_PROTOCOLS, buildAsyncApiServerBaseUrl, buildConnectionUrl, buildWsQueryParams, getAsyncApiServerVariables, getUrlSchemeFromProtocol, isWebSocketProtocol, mergeWsBindings, } from './build-connection-url.js';
+export { getAsyncApiServers, getSelectedAsyncApiServer } from './servers.js';

package/dist/channel-example/servers.d.ts

@@ -0,0 +1,36 @@
+import type { AsyncApiChannelObject, AsyncApiDocument, AsyncApiOperationObject, AsyncApiServerObject } from '@scalar/types/asyncapi/3.1';
+import { type BuildConnectionUrlInput } from '../channel-example/build-connection-url.js';
+import type { WorkspaceDocument } from '../schemas/workspace.js';
+export type AsyncApiServerListOptions = {
+    channel?: AsyncApiChannelObject | null;
+    operation?: AsyncApiOperationObject | null;
+    pathParameters?: Record<string, string>;
+    queryParameters?: Record<string, string>;
+    environmentVariables?: BuildConnectionUrlInput['environmentVariables'];
+    /** When true (default), only servers with `ws` or `wss` protocol are returned. */
+    webSocketOnly?: boolean;
+};
+export type AsyncApiServerEntry = {
+    /** Key in `document.servers`. */
+    name: string;
+    server: AsyncApiServerObject;
+    host: string;
+    protocol: string;
+    description?: string;
+    title?: string;
+    /** Base URL (scheme + host + pathname) without the channel address. */
+    url: string;
+    /** Full WebSocket URL when `channel` is provided in list options. */
+    connectionUrl?: string;
+    /** Whether this server uses a WebSocket protocol (`ws` / `wss`). */
+    isWebSocket: boolean;
+};
+/**
+ * Returns a normalized list of AsyncAPI servers with computed base `url` and optional `connectionUrl`.
+ */
+export declare const getAsyncApiServers: (document: AsyncApiDocument, options?: AsyncApiServerListOptions) => AsyncApiServerEntry[];
+/**
+ * Returns the selected AsyncAPI server entry, using `x-scalar-selected-asyncapi-server` on the document.
+ */
+export declare const getSelectedAsyncApiServer: (document: WorkspaceDocument | null, servers: AsyncApiServerEntry[], _operation?: AsyncApiOperationObject | null) => AsyncApiServerEntry | null;
+//# sourceMappingURL=servers.d.ts.map

package/dist/channel-example/servers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"servers.d.ts","sourceRoot":"","sources":["../../src/channel-example/servers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EACL,KAAK,uBAAuB,EAI7B,MAAM,wCAAwC,CAAA;AAG/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAA;IACtC,SAAS,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAA;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,oBAAoB,CAAC,EAAE,uBAAuB,CAAC,sBAAsB,CAAC,CAAA;IACtE,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,oBAAoB,CAAA;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oEAAoE;IACpE,WAAW,EAAE,OAAO,CAAA;CACrB,CAAA;AAKD;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,gBAAgB,EAC1B,UAAS,yBAA8B,KACtC,mBAAmB,EA4CrB,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,iBAAiB,GAAG,IAAI,EAClC,SAAS,mBAAmB,EAAE,EAC9B,aAAa,uBAAuB,GAAG,IAAI,KAC1C,mBAAmB,GAAG,IAYxB,CAAA"}

package/dist/channel-example/servers.js

@@ -0,0 +1,54 @@
+import { objectEntries } from '@scalar/helpers/object/object-entries';
+import { buildAsyncApiServerBaseUrl, buildConnectionUrl, isWebSocketProtocol, } from '../channel-example/build-connection-url.js';
+import { getResolvedRef } from '../helpers/get-resolved-ref.js';
+import { isAsyncApiDocument } from '../schemas/type-guards.js';
+const resolveServer = (server) => getResolvedRef(server);
+/**
+ * Returns a normalized list of AsyncAPI servers with computed base `url` and optional `connectionUrl`.
+ */
+export const getAsyncApiServers = (document, options = {}) => {
+    const { channel = null, operation = null, pathParameters = {}, queryParameters = {}, environmentVariables, webSocketOnly = true, } = options;
+    const servers = document.servers ?? {};
+    return objectEntries(servers)
+        .map(([name, serverRef]) => {
+        const server = resolveServer(serverRef);
+        const protocol = server.protocol.trim().toLowerCase();
+        const isWebSocket = isWebSocketProtocol(protocol);
+        const url = buildAsyncApiServerBaseUrl(server, environmentVariables);
+        const entry = {
+            name,
+            server,
+            host: server.host,
+            protocol,
+            description: server.description,
+            title: server.title,
+            url,
+            isWebSocket,
+        };
+        if (channel) {
+            entry.connectionUrl = buildConnectionUrl({
+                server,
+                channel,
+                operation,
+                pathParameters,
+                queryParameters,
+                environmentVariables,
+            });
+        }
+        return entry;
+    })
+        .filter((entry) => (webSocketOnly ? entry.isWebSocket : true));
+};
+/**
+ * Returns the selected AsyncAPI server entry, using `x-scalar-selected-asyncapi-server` on the document.
+ */
+export const getSelectedAsyncApiServer = (document, servers, _operation) => {
+    if (!isAsyncApiDocument(document)) {
+        return servers[0] ?? null;
+    }
+    const selectedName = document['x-scalar-selected-server'];
+    if (selectedName == null) {
+        return servers[0] ?? null;
+    }
+    return servers.find(({ name }) => name === selectedName) ?? servers[0] ?? null;
+};