@vkma.dev/bridge 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,130 @@
+/**
+ * @vkma.dev/bridge — an independent VK Bridge for VK Mini Apps.
+ *
+ * The default export is a ready singleton; `createVKBridge` builds additional
+ * instances. Every instance carries an always-on tap (see `onSend`/`onEvent`
+ * and `tap`), which is what the VKMA devtools observe — no opt-in required.
+ *
+ * Merely importing this module publishes the page-wide devtools handle on
+ * `globalThis.__vkmaDevtoolsBridge` (`{ tap, send }`), so the devtools
+ * collector — loaded as a separate script, never sharing a module graph with
+ * the app — can observe and drive the app's own bridge instance.
+ */
+
+import packageJson from "../package.json" with { type: "json" };
+import { createVKBridge, type VkmaBridgeOptions } from "./bridge.ts";
+import { createTap, type BridgeTap, type BridgeTapEvent } from "./tap.ts";
+
+export { createVKBridge, type RequestIdPolicy, type VkmaBridgeOptions } from "./bridge.ts";
+import type { VkmaBridge } from "./types.ts";
+export { applyMiddleware, type Middleware, type MiddlewareAPI } from "./middleware.ts";
+export { parseURLSearchParamsForGetLaunchParams, type LaunchParams } from "./launch-params.ts";
+export { createTap } from "./tap.ts";
+export type {
+	SendOptions,
+	VKBridge,
+	VKBridgeErrorEvent,
+	VKBridgeEvent,
+	VKBridgeEventBase,
+	VKBridgeIOEvent,
+	VKBridgeReceiveOnlyEvent,
+	VKBridgeResultEvent,
+	VKBridgeSend,
+	VKBridgeSubscribeHandler,
+	VkmaBridge,
+	AnyIOMethodName,
+	AnyMethodName,
+	AnyReceiveMethodName,
+	AnyReceiveOnlyMethodName,
+	AnyRequestMethodName,
+	AnyRequestOnlyMethodName,
+	ErrorData,
+	ErrorDataAPIError,
+	ErrorDataAuthError,
+	ErrorDataClientError,
+	FailedResponseEventName,
+	RequestIdProp,
+	RequestProps,
+	ReceiveData,
+	ResultResponseEventName,
+} from "./types.ts";
+export type {
+	RequestMethodName,
+	ReceiveMethodName,
+	RequestOnlyMethodName,
+	ReceiveOnlyMethodName,
+	MethodName,
+	IOMethodName,
+	WidgetType,
+} from "./deprecated.ts";
+export type { ReceiveDataMap, ReceiveEventMap, RequestPropsMap } from "@vkma.dev/bridge-schema";
+export * from "@vkma.dev/bridge-schema";
+
+/**
+ * The devtools bridge handle shared by every copy of this module on the page,
+ * exposed on `globalThis` under a stable key so the devtools collector —
+ * loaded as a separate script, never sharing a module graph with the app —
+ * can observe and drive the app's own bridge instance:
+ *
+ * - `tap` — replay-buffered stream of sends, paired responses and events
+ * - `send` — execute a bridge send inside the app (devtools "execute")
+ */
+const GLOBAL_KEY = "__vkmaDevtoolsBridge";
+
+export interface DevtoolsBridgeHandle {
+	tap: BridgeTap;
+	send: (name: string, params?: Record<string, unknown>) => Promise<unknown>;
+}
+
+const globalScope = globalThis as typeof globalThis & {
+	[GLOBAL_KEY]?: DevtoolsBridgeHandle;
+};
+
+function sharedTap(): BridgeTap {
+	const existing = globalScope[GLOBAL_KEY];
+	if (existing) {
+		return existing.tap;
+	}
+	const tap = createTap();
+	globalScope[GLOBAL_KEY] = {
+		tap,
+		// The collector executes arbitrary method names — the handle stays
+		// stringly typed by design.
+		send: (name, params) => bridge.send(name as never, params as never),
+	};
+	return tap;
+}
+
+/** Options of the page-wide default instance: it shares the global tap. */
+const defaultOptions: VkmaBridgeOptions = {
+	tap: sharedTap(),
+};
+
+const bridge: VkmaBridge = createVKBridge(packageJson.version, defaultOptions);
+
+/**
+ * Subscribe to outgoing `send` calls of the default instance.
+ */
+export function onSend(
+	listener: (event: BridgeTapEvent & { direction: "out" }) => void,
+): () => void {
+	return bridge.onSend(listener);
+}
+
+/**
+ * Subscribe to everything incoming on the default instance: paired responses
+ * and unsolicited events.
+ */
+export function onEvent(
+	listener: (event: BridgeTapEvent & { direction: "in" }) => void,
+): () => void {
+	return bridge.onEvent(listener);
+}
+
+/** The shared tap of the default instance (buffered until first subscribe). */
+export const bridgeTap: BridgeTap = bridge.tap;
+
+/** The `globalThis` key the devtools collector looks the handle up by. */
+export const devtoolsBridgeGlobalKey = GLOBAL_KEY;
+
+export { bridge as default };

package/src/launch-params.ts

@@ -0,0 +1,117 @@
+/**
+ * Launch params: parsing the `vk_*` query string every mini app is opened
+ * with, into the typed shape of the catalogue's `GetLaunchParamsResponse`
+ * plus the extra keys only present in the URL form.
+ */
+
+import type { GetLaunchParamsResponse } from "@vkma.dev/bridge-schema";
+
+const LANGUAGES = new Set(["ru", "uk", "ua", "en", "be", "kz", "pt", "es"]);
+
+const GROUP_ROLES = new Set(["admin", "editor", "member", "moder", "none"]);
+
+const PLATFORMS = new Set([
+	"desktop_web",
+	"desktop_web_messenger",
+	"desktop_app_messenger",
+	"mobile_web",
+	"mobile_android",
+	"mobile_android_messenger",
+	"mobile_iphone",
+	"mobile_iphone_messenger",
+	"mobile_ipad",
+]);
+
+/**
+ * Launch params as they appear in the URL — a superset of
+ * `GetLaunchParamsResponse` with the keys the host only sends via the query
+ * string.
+ */
+export interface LaunchParams extends GetLaunchParamsResponse {
+	vk_chat_id: string;
+	vk_is_recommended: number;
+	vk_profile_id: number;
+	vk_has_profile_button: number;
+	vk_testing_group_id: number;
+	odr_enabled: undefined | 1;
+}
+
+/**
+ * Parses launch params out of a query string (à la
+ * `location.search.slice(1)`), field by field, keeping only the known keys
+ * with validated values.
+ *
+ * @see https://dev.vk.ru/mini-apps/development/launch-params
+ */
+export const parseURLSearchParamsForGetLaunchParams = (
+	searchParams: string,
+): Partial<LaunchParams> => {
+	const launchParams: Partial<LaunchParams> = {};
+
+	try {
+		const parsedSearchParams = new URLSearchParams(searchParams);
+
+		const convertToggleStateFromStringToNumber = (value: string): 0 | 1 | undefined => {
+			switch (value) {
+				case "0":
+					return 0;
+				case "1":
+					return 1;
+				default:
+					return undefined;
+			}
+		};
+
+		parsedSearchParams.forEach((value, query) => {
+			switch (query) {
+				case "vk_ts":
+				case "vk_is_recommended":
+				case "vk_profile_id":
+				case "vk_has_profile_button":
+				case "vk_testing_group_id":
+				case "vk_user_id":
+				case "vk_app_id":
+				case "vk_group_id":
+					launchParams[query] = Number(value);
+					break;
+				case "sign":
+				case "vk_chat_id":
+				case "vk_ref":
+				case "vk_access_token_settings":
+					launchParams[query] = value;
+					break;
+				case "odr_enabled":
+					launchParams.odr_enabled = value === "1" ? 1 : undefined;
+					break;
+				case "vk_is_app_user":
+				case "vk_are_notifications_enabled":
+				case "vk_is_favorite": {
+					launchParams[query] = convertToggleStateFromStringToNumber(value);
+					break;
+				}
+				case "vk_language": {
+					launchParams.vk_language = LANGUAGES.has(value)
+						? (value as Partial<LaunchParams>["vk_language"])
+						: undefined;
+					break;
+				}
+				case "vk_viewer_group_role": {
+					launchParams.vk_viewer_group_role = GROUP_ROLES.has(value)
+						? (value as Partial<LaunchParams>["vk_viewer_group_role"])
+						: undefined;
+					break;
+				}
+				case "vk_platform": {
+					launchParams.vk_platform = PLATFORMS.has(value)
+						? (value as Partial<LaunchParams>["vk_platform"])
+						: undefined;
+					break;
+				}
+			}
+		});
+	} catch (error) {
+		console.warn(error);
+	}
+
+	return launchParams;
+};

package/src/middleware.ts

@@ -0,0 +1,70 @@
+/**
+ * Redux-style middleware over `send`: compose logging, metrics or caching
+ * around the dispatch without touching the transport.
+ */
+
+import type { VKBridge, VKBridgeSend, VKBridgeSubscribeHandler } from "./types.ts";
+
+/**
+ * API that can use middleware.
+ */
+export interface MiddlewareAPI<
+	S extends VKBridgeSend = VKBridgeSend,
+	L extends VKBridgeSubscribeHandler = VKBridgeSubscribeHandler,
+> {
+	send: S;
+	subscribe(listener: L): void;
+}
+
+/**
+ * A middleware is a higher-order function that composes a dispatch function
+ * to return a new `send` function.
+ */
+export type Middleware<S extends VKBridgeSend = VKBridgeSend> = (
+	api: MiddlewareAPI<S>,
+) => (next: S) => S;
+
+/**
+ * Creates the VK Bridge enhancer that applies middleware to the `send`
+ * method. This is handy for a variety of tasks such as logging every sent
+ * event.
+ *
+ * @param middlewares The middleware chain to be applied.
+ * @returns The VK Bridge enhancer applying the middleware.
+ */
+export function applyMiddleware(
+	...middlewares: Array<Middleware | undefined | null>
+): (bridge: VKBridge) => VKBridge {
+	if (middlewares.includes(undefined) || middlewares.includes(null)) {
+		return applyMiddleware(
+			...middlewares.filter((item): item is Middleware => typeof item === "function"),
+		);
+	}
+
+	return bridge => {
+		if (middlewares.length === 0) {
+			return bridge;
+		}
+
+		let send: VKBridgeSend = () => {
+			throw new Error(
+				"Sending events while constructing your middleware is not allowed. " +
+					"Other middleware would not be applied to this send.",
+			);
+		};
+
+		const middlewareAPI: MiddlewareAPI = {
+			subscribe: bridge.subscribe,
+			send: ((...args: Parameters<VKBridgeSend>) => bridge.send(...args)) as VKBridgeSend,
+		};
+
+		const chain = middlewares
+			.filter((item): item is Middleware => typeof item === "function")
+			.map(middleware => middleware(middlewareAPI))
+			.reduce((a, b) => next => a(b(next)));
+
+		send = chain(bridge.send);
+
+		return { ...bridge, send };
+	};
+}

package/src/tap.ts

@@ -0,0 +1,77 @@
+/**
+ * Pure tap machinery: a tiny fan-out hub with a bounded replay buffer,
+ * detached from vk-bridge so it is unit-testable and tree-shakeable.
+ *
+ * The bridge wrapper always emits into the tap. When no devtools collector
+ * is attached (production), the buffer fills up once and every later emit
+ * costs a dropped-head push — effectively free.
+ */
+
+export interface BridgeTapEvent {
+	/** Monotonic within a page load; pairs a `response` with its `send`. */
+	id: number;
+	ts: number;
+	/** `out` — the app called send; `in` — VK sent something to the app. */
+	direction: "out" | "in";
+	/** `send` (out), `response` (in, paired), `event` (in, unsolicited). */
+	kind: "send" | "response" | "event";
+	name: string;
+	payload?: unknown;
+	/** Response pairing: the id of the originating `send` event. */
+	reqId?: number;
+	/** Only for `response`: whether the promise resolved or rejected. */
+	ok?: boolean;
+}
+
+export interface BridgeTap {
+	emit(event: Omit<BridgeTapEvent, "id" | "ts"> & { ts?: number }): number;
+	subscribe(listener: (event: BridgeTapEvent) => void): () => void;
+	/** Events buffered before the first subscriber attached, oldest first. */
+	drain(): BridgeTapEvent[];
+}
+
+const DEFAULT_BUFFER_LIMIT = 500;
+
+export function createTap(limit: number = DEFAULT_BUFFER_LIMIT): BridgeTap {
+	let nextId = 0;
+	let buffer: BridgeTapEvent[] | undefined = [];
+	const listeners = new Set<(event: BridgeTapEvent) => void>();
+
+	return {
+		emit(partial) {
+			const event: BridgeTapEvent = {
+				...partial,
+				id: ++nextId,
+				ts: partial.ts ?? Date.now(),
+			};
+			if (listeners.size === 0) {
+				// No collector yet (production or devtools not loaded): keep a
+				// bounded replay so a late-attaching collector still sees recent
+				// history, then stop growing work at the cap.
+				if (buffer && buffer.length >= limit) {
+					buffer.shift();
+				}
+				buffer?.push(event);
+				return event.id;
+			}
+			for (const listener of listeners) {
+				listener(event);
+			}
+			return event.id;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			const replay = buffer ?? [];
+			buffer = undefined;
+			for (const event of replay) {
+				listener(event);
+			}
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		drain() {
+			return buffer ? [...buffer] : [];
+		},
+	};
+}

package/src/types.ts

@@ -0,0 +1,271 @@
+/**
+ * Bridge machinery types, built on top of the @vkma.dev/bridge-schema
+ * catalogue. The payload types and the three catalogue maps
+ * (`RequestPropsMap` / `ReceiveDataMap` / `ReceiveEventMap`) are re-exported
+ * from the schema package by the public entrypoint; everything here is the
+ * send/subscribe/event plumbing around them.
+ */
+
+import type { ReceiveDataMap, ReceiveEventMap, RequestPropsMap } from "@vkma.dev/bridge-schema";
+import type { BridgeTap, BridgeTapEvent } from "./tap.ts";
+
+/**
+ * Name of a method that can be sent.
+ */
+export type AnyRequestMethodName = keyof RequestPropsMap;
+
+/**
+ * Name of a method that can be received.
+ */
+export type AnyReceiveMethodName = keyof ReceiveDataMap;
+
+/**
+ * Name of a method that can be only sent.
+ */
+export type AnyRequestOnlyMethodName = Exclude<AnyRequestMethodName, AnyReceiveMethodName>;
+
+/**
+ * Name of a method that can be only received.
+ */
+export type AnyReceiveOnlyMethodName = Exclude<AnyReceiveMethodName, AnyRequestMethodName>;
+
+/**
+ * Type of any method name.
+ */
+export type AnyMethodName = AnyRequestMethodName | AnyReceiveMethodName;
+
+/**
+ * The name of the method that can be both sent and received.
+ */
+export type AnyIOMethodName = AnyRequestMethodName & AnyReceiveMethodName;
+
+/**
+ * Getter of request properties of a method.
+ */
+export type RequestProps<M extends AnyRequestMethodName = AnyRequestMethodName> =
+	RequestPropsMap[M];
+
+/**
+ * Getter of response data of a method.
+ */
+export type ReceiveData<M extends AnyReceiveMethodName> = ReceiveDataMap[M];
+
+/**
+ * Property for matching a sent request with the received message.
+ */
+export type RequestIdProp = { request_id?: number | string };
+
+/**
+ * Extra per-send controls on top of the classic two-argument call.
+ */
+export interface SendOptions {
+	/** Reject the promise if no response arrives within this many milliseconds. */
+	timeout?: number;
+	/** Reject the promise when the signal aborts. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Type of send function for methods that have props.
+ *
+ * @param method The method (event) name to send.
+ * @param props Method properties.
+ * @param options Timeout / abort controls.
+ * @returns The Promise object with response data.
+ */
+export type VKBridgeSend = <K extends AnyRequestMethodName>(
+	method: K,
+	props?: RequestProps<K> & RequestIdProp,
+	options?: SendOptions,
+) => Promise<K extends AnyReceiveMethodName ? ReceiveData<K> : void>;
+
+/**
+ * Name of the Result response event of a method (per the catalogue wiring).
+ */
+export type ResultResponseEventName<M extends AnyRequestMethodName> =
+	M extends keyof ReceiveEventMap ? ReceiveEventMap[M]["result"] : never;
+
+/**
+ * Name of the Failed response event of a method (per the catalogue wiring).
+ */
+export type FailedResponseEventName<M extends AnyRequestMethodName> =
+	M extends keyof ReceiveEventMap ? ReceiveEventMap[M]["failed"] : never;
+
+/**
+ * Client error data.
+ */
+export type ErrorDataClientError = {
+	error_code: number;
+	error_reason: string;
+	error_description?: string;
+};
+
+/**
+ * API error data.
+ */
+export type ErrorDataAPIError = {
+	error_code: number;
+	error_msg: string;
+	request_params: string[];
+};
+
+/**
+ * Auth error data.
+ */
+export type ErrorDataAuthError = {
+	error_code: number;
+	error_reason: string;
+	error_description?: string[];
+};
+
+/**
+ * Error data of a Failed response event.
+ */
+export type ErrorData =
+	| {
+			error_type: "client_error";
+			error_data: ErrorDataClientError;
+			request_id?: number | string;
+	  }
+	| {
+			error_type: "api_error";
+			error_data: ErrorDataAPIError;
+			request_id?: number | string;
+	  }
+	| {
+			error_type: "auth_error";
+			error_data: ErrorDataAuthError;
+			request_id?: number | string;
+	  };
+
+/**
+ * Generic event type for creating event types.
+ */
+export type VKBridgeEventBase<Type extends string, Data> = {
+	detail: {
+		type: Type;
+		data: Data;
+	};
+};
+
+/**
+ * Type of error event data.
+ */
+export type VKBridgeErrorEvent<M extends AnyReceiveMethodName> = VKBridgeEventBase<
+	M extends AnyRequestMethodName ? FailedResponseEventName<M> : never,
+	ErrorData
+>;
+
+/**
+ * Type of event that is a response to a request.
+ */
+export type VKBridgeIOEvent<M extends AnyIOMethodName> = {
+	[K in M]: VKBridgeEventBase<ResultResponseEventName<K>, ReceiveData<K> & RequestIdProp>;
+}[M];
+
+/**
+ * Type of event that is not a response to a request.
+ */
+export type VKBridgeReceiveOnlyEvent<M extends AnyReceiveOnlyMethodName> = {
+	[K in M]: VKBridgeEventBase<K, ReceiveData<K>>;
+}[M];
+
+/**
+ * Type of result event data.
+ */
+export type VKBridgeResultEvent<M extends AnyReceiveMethodName> = M extends AnyReceiveOnlyMethodName
+	? VKBridgeReceiveOnlyEvent<M>
+	: M extends AnyIOMethodName
+		? VKBridgeIOEvent<M>
+		: never;
+
+/**
+ * VK Bridge event.
+ */
+export type VKBridgeEvent<M extends AnyReceiveMethodName> =
+	| VKBridgeErrorEvent<M>
+	| VKBridgeResultEvent<M>;
+
+/**
+ * Type of function that can be subscribed to VK Bridge events.
+ */
+export type VKBridgeSubscribeHandler = (event: VKBridgeEvent<AnyReceiveMethodName>) => void;
+
+/**
+ * VK Bridge interface — the classic drop-in surface.
+ */
+export interface VKBridge {
+	/**
+	 * Sends an event to the runtime env and returns the Promise object with
+	 * response data. In the case of Android/iOS application env is the
+	 * application itself. In the case of the browser, the parent frame in
+	 * which the event handlers is located.
+	 *
+	 * @param method The method (event) name to send.
+	 * @param [props] Method properties.
+	 * @param [options] Timeout / abort controls.
+	 * @returns The Promise object with response data.
+	 */
+	send: VKBridgeSend;
+
+	/**
+	 * @alias send
+	 * @deprecated
+	 */
+	sendPromise: VKBridgeSend;
+
+	/**
+	 * Adds an event listener. It will be called any time a data is received.
+	 *
+	 * @param listener A callback to be invoked on every event receive.
+	 */
+	subscribe: (listener: VKBridgeSubscribeHandler) => void;
+
+	/**
+	 * Removes an event listener which has been subscribed for event listening.
+	 *
+	 * @param listener A callback to unsubscribe.
+	 */
+	unsubscribe: (listener: VKBridgeSubscribeHandler) => void;
+
+	/**
+	 * Checks if a method is supported on runtime platform.
+	 *
+	 * @param method Method (event) name to check.
+	 * @returns Result of checking.
+	 * @deprecated This method is deprecated. Use supportsAsync instead.
+	 */
+	supports: <K extends AnyRequestMethodName>(method: K) => boolean;
+
+	/**
+	 * Checks if a method is supported on runtime platform.
+	 *
+	 * @param method Method (event) name to check.
+	 * @returns The Promise object with result of checking.
+	 */
+	supportsAsync: <K extends AnyRequestMethodName>(method: K) => Promise<boolean>;
+
+	/**
+	 * Checks whether the runtime is a WebView.
+	 */
+	isWebView: () => boolean;
+
+	isIframe: () => boolean;
+
+	isEmbedded: () => boolean;
+
+	isStandalone: () => boolean;
+}
+
+/**
+ * The full instance surface: the classic VK Bridge plus the always-on tap
+ * and its subscription helpers.
+ */
+export interface VkmaBridge extends VKBridge {
+	/** The replay-buffered stream of sends, paired responses and events. */
+	tap: BridgeTap;
+	/** Subscribe to outgoing `send` calls. */
+	onSend: (listener: (event: BridgeTapEvent & { direction: "out" }) => void) => () => void;
+	/** Subscribe to everything incoming: paired responses and unsolicited events. */
+	onEvent: (listener: (event: BridgeTapEvent & { direction: "in" }) => void) => () => void;
+}