@vkma.dev/bridge 0.0.0-stage → 0.2.1

package/src/deprecated.ts

@@ -0,0 +1,61 @@
+/**
+ * Pre-`Any*` type names, kept as aliases so older code keeps compiling.
+ */
+
+import type { CommunityWidgetType } from "@vkma.dev/bridge-schema";
+import type {
+	AnyIOMethodName,
+	AnyReceiveMethodName,
+	AnyReceiveOnlyMethodName,
+	AnyRequestMethodName,
+	AnyRequestOnlyMethodName,
+} from "./types.ts";
+
+/**
+ * Name of a method that can be sent.
+ * @alias AnyRequestMethodName
+ * @deprecated
+ */
+export type RequestMethodName = AnyRequestMethodName;
+
+/**
+ * Name of a method that can be received.
+ * @alias AnyReceiveMethodName
+ * @deprecated
+ */
+export type ReceiveMethodName = AnyReceiveMethodName;
+
+/**
+ * Name of a method that can be only sent.
+ * @alias AnyRequestOnlyMethodName
+ * @deprecated
+ */
+export type RequestOnlyMethodName = AnyRequestOnlyMethodName;
+
+/**
+ * Name of a method that can be only received.
+ * @alias AnyReceiveOnlyMethodName
+ * @deprecated
+ */
+export type ReceiveOnlyMethodName = AnyReceiveOnlyMethodName;
+
+/**
+ * Type of any method name.
+ * @alias AnyMethodName
+ * @deprecated
+ */
+export type MethodName = AnyRequestMethodName | AnyReceiveMethodName;
+
+/**
+ * The name of the method that can be both sent and received.
+ * @alias AnyIOMethodName
+ * @deprecated
+ */
+export type IOMethodName = AnyIOMethodName;
+
+/**
+ * Community widget type
+ * @alias CommunityWidgetType
+ * @deprecated
+ */
+export type WidgetType = CommunityWidgetType;

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,131 @@
+/**
+ * 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",
+	"desktop_web_ok",
+	"mobile_web",
+	"mobile_web_ok",
+	"mobile_android",
+	"mobile_android_ok",
+	"mobile_android_messenger",
+	"mobile_iphone",
+	"mobile_iphone_ok",
+	"mobile_iphone_messenger",
+	"mobile_ipad",
+]);
+
+/**
+ * Launch params as they appear in the URL — a superset of
+ * `GetLaunchParamsResponse` with the URL-only keys. The OK (Odnoklassniki)
+ * keys (`vk_client`, `vk_ok_*`, `vk_original_vk_id`, `vk_are_pushes_enabled`)
+ * come from the catalogue as optional — vk.com hosts never send them.
+ */
+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 => {
+			// OK hosts serialize toggles both ways ("true"/"false" and "0"/"1")
+			switch (value) {
+				case "0":
+				case "false":
+					return 0;
+				case "1":
+				case "true":
+					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":
+				case "vk_ok_app_id":
+				case "vk_ok_user_id":
+				case "vk_original_vk_id":
+					launchParams[query] = Number(value);
+					break;
+				case "sign":
+				case "vk_chat_id":
+				case "vk_ref":
+				case "vk_ok_ref":
+				case "vk_client":
+				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_are_pushes_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] : [];
+		},
+	};
+}