@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/asyncapi/normalise-3.js

@@ -0,0 +1,133 @@
+/**
+ * AsyncAPI 3.0 into the version-neutral view.
+ *
+ * A 3.0 operation's `action` is the described application's: `receive` is what it accepts, so
+ * Wirebench — its peer — sends it, and `send` is what it emits, which Wirebench receives. A `reply`
+ * travels the other way from its operation.
+ */
+import { channelParameter, deref, entries, isJsonSchemaFormat, isRecord, localRef, message, record, refKey, securityScheme, str, substitute, tagNames, } from './read.js';
+function payloadOf(node) {
+    const payload = node['payload'];
+    // A multi-format schema object carries its format beside the schema.
+    if (isRecord(payload) && 'schema' in payload && typeof payload['schemaFormat'] === 'string') {
+        return { payload: payload['schema'], schemaFormat: payload['schemaFormat'] };
+    }
+    return payload !== undefined ? { payload } : {};
+}
+/** The channel key a raw `{ $ref: '#/channels/<key>' }` names. */
+function channelKey(rawNode) {
+    const tokens = localRef(rawNode);
+    return tokens?.length === 2 && tokens[0] === 'channels' ? tokens[1] : undefined;
+}
+/**
+ * @param raw the parsed document before `$ref` inlining, where the keys references name still are
+ * @param resolved the same document with references inlined
+ */
+export function normaliseAsyncApi3(raw, resolved, declaredVersion) {
+    const notes = [];
+    const defaultContentType = str(resolved['defaultContentType']) ?? 'application/json';
+    const rawServers = record(raw['servers']);
+    const servers = entries(resolved['servers']).map(([key, server]) => {
+        const protocol = str(server['protocol']) ?? '';
+        const written = `${str(server['host']) ?? ''}${str(server['pathname']) ?? ''}`;
+        const { value, unresolved } = substitute(written, server['variables']);
+        const rawSecurity = record(deref(raw, rawServers[key]))['security'];
+        const security = Array.isArray(server['security']) ? server['security'] : [];
+        return {
+            key,
+            url: protocol === '' ? value : `${protocol}://${value}`,
+            protocol,
+            security: security.flatMap((scheme, index) => {
+                if (!isRecord(scheme))
+                    return [];
+                const rawOne = Array.isArray(rawSecurity) ? rawSecurity[index] : undefined;
+                return [securityScheme(refKey(rawOne) ?? `${key}#security${String(index)}`, scheme)];
+            }),
+            unresolvedVariables: unresolved,
+        };
+    });
+    const rawChannels = record(raw['channels']);
+    const channelMessages = new Map();
+    const channels = entries(resolved['channels']).map(([key, channel]) => {
+        channelMessages.set(key, entries(channel['messages']).map(([messageKey, node]) => {
+            const read = message(messageKey, node, defaultContentType, payloadOf, false);
+            if (!isJsonSchemaFormat(read.schemaFormat)) {
+                notes.push({
+                    where: `channels/${key}/messages/${messageKey}`,
+                    reason: `the payload uses ${String(read.schemaFormat)}, which is not JSON Schema`,
+                });
+            }
+            return read;
+        }));
+        const rawListed = record(deref(raw, rawChannels[key]))['servers'];
+        const listed = Array.isArray(rawListed)
+            ? rawListed.map((node) => refKey(node)).filter((k) => k !== undefined)
+            : [];
+        return {
+            key,
+            address: str(channel['address']) ?? null,
+            servers: listed.length > 0 ? listed : 'all',
+            parameters: Object.fromEntries(entries(channel['parameters']).map(([name, parameter]) => [name, channelParameter(parameter)])),
+            bindings: record(channel['bindings']),
+            tags: tagNames(channel['tags']),
+        };
+    });
+    /** The messages a raw list of `#/channels/<c>/messages/<m>` refs names, else the channel's all. */
+    const pick = (channel, rawList, where) => {
+        const all = channelMessages.get(channel) ?? [];
+        if (!Array.isArray(rawList))
+            return all;
+        return rawList.flatMap((node) => {
+            const key = refKey(node);
+            const found = all.find((m) => m.key === key);
+            if (found === undefined) {
+                notes.push({ where, reason: `the message ${key ?? 'written inline'} is not one of channel ${channel}'s` });
+                return [];
+            }
+            return [found];
+        });
+    };
+    const operations = [];
+    const rawOperations = record(raw['operations']);
+    for (const [key] of entries(resolved['operations'])) {
+        const where = `operations/${key}`;
+        const rawOperation = record(deref(raw, rawOperations[key]));
+        const action = rawOperation['action'];
+        const direction = action === 'receive' ? 'sent' : action === 'send' ? 'received' : undefined;
+        if (direction === undefined) {
+            notes.push({ where, reason: `the action ${String(action)} is neither send nor receive` });
+            continue;
+        }
+        const channel = channelKey(rawOperation['channel']);
+        if (channel === undefined || !channelMessages.has(channel)) {
+            notes.push({ where, reason: 'the operation does not reference a channel of this document' });
+            continue;
+        }
+        operations.push({ key, channel, direction, messages: pick(channel, rawOperation['messages'], where) });
+        const rawReply = deref(raw, rawOperation['reply']);
+        if (isRecord(rawReply)) {
+            if (rawReply['channel'] === undefined && rawReply['address'] !== undefined) {
+                notes.push({
+                    where: `${where}/reply`,
+                    reason: "the reply's address is set at run time; it is mapped onto the operation's channel",
+                });
+            }
+            const replyChannel = channelKey(rawReply['channel']) ?? channel;
+            operations.push({
+                key: `${key}#reply`,
+                channel: replyChannel,
+                direction: direction === 'sent' ? 'received' : 'sent',
+                messages: pick(replyChannel, rawReply['messages'], `${where}/reply`),
+            });
+        }
+    }
+    return {
+        version: '3',
+        declaredVersion,
+        title: str(record(resolved['info'])['title']) ?? '',
+        servers,
+        channels,
+        operations,
+        notes,
+    };
+}

package/dist/asyncapi/parse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Reading an AsyncAPI 2.x or 3.0 document into the version-neutral view.
+ *
+ * The fetch, the `$ref` resolution and the source shapes are the OpenAPI import's own, so the
+ * documents it hands back are what the definition cache already knows how to store. Only two
+ * things are fatal: text that is not a document, and a version this reader does not know.
+ * Everything else that cannot be mapped becomes a note on the document.
+ */
+import type { OpenApiSource } from '../json/schema/source.js';
+import { type RefProblem, type ResolvedDocument } from '../json/schema/refs.js';
+import type { FetchDocument } from '../http/fetch-document.js';
+import type { AsyncApiDocument } from './model.js';
+export interface ParseAsyncApiOptions {
+    readonly fetchDocument: FetchDocument;
+    readonly signal?: AbortSignal;
+}
+/** A parsed document and everything it was made of. */
+export interface ParsedAsyncApi {
+    readonly document: AsyncApiDocument;
+    /** Every file fetched, root first — what the definition cache stores. */
+    readonly documents: readonly ResolvedDocument[];
+    /** References that could not be followed. The import continues without them. */
+    readonly problems: readonly RefProblem[];
+}
+/**
+ * Fetches (when needed), resolves and normalises one AsyncAPI document.
+ *
+ * @throws AsyncApiError `asyncapi-malformed` or `asyncapi-version-unsupported`; an `AbortError`
+ * when the signal fires mid-fetch.
+ */
+export declare function parseAsyncApi(source: OpenApiSource, options: ParseAsyncApiOptions): Promise<ParsedAsyncApi>;

package/dist/asyncapi/parse.js

@@ -0,0 +1,85 @@
+/**
+ * Reading an AsyncAPI 2.x or 3.0 document into the version-neutral view.
+ *
+ * The fetch, the `$ref` resolution and the source shapes are the OpenAPI import's own, so the
+ * documents it hands back are what the definition cache already knows how to store. Only two
+ * things are fatal: text that is not a document, and a version this reader does not know.
+ * Everything else that cannot be mapped becomes a note on the document.
+ */
+import { AsyncApiError, OpenApiError } from '../errors.js';
+import { parseDocumentText } from '../json/schema/parse-text.js';
+import { resolveRefs } from '../json/schema/refs.js';
+import { normaliseAsyncApi2 } from './normalise-2.js';
+import { normaliseAsyncApi3 } from './normalise-3.js';
+import { isRecord } from './read.js';
+function locationOf(source) {
+    if (source.kind === 'url')
+        return source.url;
+    if (source.kind === 'file') {
+        if (!source.path.startsWith('file:')) {
+            throw new AsyncApiError('asyncapi-malformed', 'A file source must be given as a file: URL', {
+                details: { path: source.path },
+            });
+        }
+        return source.path;
+    }
+    return source.location ?? 'inline:asyncapi';
+}
+/** Which normaliser a declared version goes to, or a refusal naming it. */
+function majorOf(declared) {
+    if (/^2\.[0-6](?:\.\d+)?$/.test(declared))
+        return '2';
+    if (/^3\.0(?:\.\d+)?$/.test(declared))
+        return '3';
+    throw new AsyncApiError('asyncapi-version-unsupported', `AsyncAPI ${declared} is not supported; 2.0 to 2.6 and 3.0 are`, {
+        details: { version: declared },
+    });
+}
+function parseRoot(text, where) {
+    try {
+        return parseDocumentText(text, where);
+    }
+    catch (error) {
+        if (error instanceof OpenApiError) {
+            throw new AsyncApiError('asyncapi-malformed', error.message, { cause: error });
+        }
+        throw error;
+    }
+}
+/**
+ * Fetches (when needed), resolves and normalises one AsyncAPI document.
+ *
+ * @throws AsyncApiError `asyncapi-malformed` or `asyncapi-version-unsupported`; an `AbortError`
+ * when the signal fires mid-fetch.
+ */
+export async function parseAsyncApi(source, options) {
+    const location = locationOf(source);
+    let text;
+    let bytes;
+    let rootLocation = location;
+    if (source.kind === 'text') {
+        text = source.text;
+    }
+    else {
+        const fetched = await options.fetchDocument(location, options.signal);
+        text = fetched.text;
+        bytes = fetched.bytes;
+        rootLocation = fetched.location;
+    }
+    const raw = parseRoot(text, rootLocation);
+    if (!isRecord(raw)) {
+        throw new AsyncApiError('asyncapi-malformed', `${rootLocation} is not an AsyncAPI document`);
+    }
+    const declared = raw['asyncapi'];
+    if (typeof declared !== 'string') {
+        throw new AsyncApiError('asyncapi-malformed', `${rootLocation} has no asyncapi version`);
+    }
+    const major = majorOf(declared);
+    const resolved = await resolveRefs(text, rootLocation, { fetchDocument: options.fetchDocument, ...(options.signal !== undefined ? { signal: options.signal } : {}) }, bytes);
+    const document = isRecord(resolved.document) ? resolved.document : {};
+    return {
+        document: major === '2' ? normaliseAsyncApi2(raw, document, declared) : normaliseAsyncApi3(raw, document, declared),
+        documents: resolved.documents,
+        problems: resolved.problems,
+    };
+}

package/dist/asyncapi/read.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Small readers both normalisers share. They take plain objects (the parsed document before and
+ * after `$ref` inlining) and never throw: a shape they do not recognise reads as absent.
+ */
+import type { AsyncApiChannelParameter, AsyncApiMessage, AsyncApiSecurityScheme } from './model.js';
+export type Json = Readonly<Record<string, unknown>>;
+export declare function isRecord(value: unknown): value is Json;
+export declare function record(value: unknown): Json;
+export declare function entries(value: unknown): [string, Json][];
+export declare function str(value: unknown): string | undefined;
+/** The pointer tokens of a local `$ref` (`#/a/b` → `['a','b']`), or undefined for any other node. */
+export declare function localRef(node: unknown): string[] | undefined;
+/** The last pointer token of any `$ref` (local or into another file) — the key the target is filed under. */
+export declare function refKey(node: unknown): string | undefined;
+/** Schema formats the contract check can read: JSON Schema, and the AsyncAPI schema that extends it. */
+export declare function isJsonSchemaFormat(format: string | undefined): boolean;
+/** Follows local `$ref`s in the raw document, a bounded number of hops, to the node they name. */
+export declare function deref(root: unknown, node: unknown): unknown;
+/** `{name}` placeholders replaced by each variable's default (else first enum value). */
+export declare function substitute(template: string, variables: unknown): {
+    value: string;
+    unresolved: string[];
+};
+export declare function securityScheme(key: string, scheme: Json): AsyncApiSecurityScheme;
+/** A channel parameter from where its values live (the 2.x `schema`, or the 3.0 parameter itself). */
+export declare function channelParameter(source: Json): AsyncApiChannelParameter;
+export declare function tagNames(value: unknown): string[];
+/**
+ * One message, traits merged in. Its name is its `name`, else its `title`, else its key. `payloadOf` pulls the schema (and a schema format carried with it) out of the
+ * version's payload shape.
+ */
+export declare function message(key: string, node: Json, defaultContentType: string, payloadOf: (node: Json) => {
+    payload?: unknown;
+    schemaFormat?: string;
+}, traitsWin: boolean): AsyncApiMessage;

package/dist/asyncapi/read.js

@@ -0,0 +1,186 @@
+/**
+ * Small readers both normalisers share. They take plain objects (the parsed document before and
+ * after `$ref` inlining) and never throw: a shape they do not recognise reads as absent.
+ */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function record(value) {
+    return isRecord(value) ? value : {};
+}
+export function entries(value) {
+    return Object.entries(record(value)).filter((entry) => isRecord(entry[1]));
+}
+export function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function scalarText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+function texts(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.map(scalarText).filter((v) => v !== undefined);
+}
+function unescapeToken(token) {
+    return token.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+/** The pointer tokens of a local `$ref` (`#/a/b` → `['a','b']`), or undefined for any other node. */
+export function localRef(node) {
+    if (!isRecord(node))
+        return undefined;
+    const ref = str(node['$ref']);
+    if (ref === undefined || !ref.startsWith('#/'))
+        return undefined;
+    return ref.slice(2).split('/').map(unescapeToken);
+}
+/** The last pointer token of any `$ref` (local or into another file) — the key the target is filed under. */
+export function refKey(node) {
+    if (!isRecord(node))
+        return undefined;
+    const ref = str(node['$ref']);
+    const hash = ref?.indexOf('#') ?? -1;
+    if (ref === undefined || hash === -1)
+        return undefined;
+    const last = ref
+        .slice(hash + 1)
+        .split('/')
+        .at(-1);
+    return last === undefined || last === '' ? undefined : unescapeToken(last);
+}
+/** Schema formats the contract check can read: JSON Schema, and the AsyncAPI schema that extends it. */
+export function isJsonSchemaFormat(format) {
+    if (format === undefined)
+        return true;
+    return /^application\/(?:schema\+(?:json|yaml)|vnd\.aai\.asyncapi(?:\+(?:json|yaml))?)(?:;|$)/i.test(format.trim());
+}
+/**
+ * A message with its `traits` shallow-merged in. In 2.x a trait is applied onto the message, so a
+ * trait's field wins; in 3.0 the message's own field wins over its traits'.
+ */
+function withTraits(node, traitsWin) {
+    const traits = node['traits'];
+    if (!Array.isArray(traits))
+        return node;
+    let merged = traitsWin ? { ...node } : {};
+    for (const trait of traits)
+        merged = { ...merged, ...record(trait) };
+    merged = traitsWin ? merged : { ...merged, ...node };
+    delete merged['traits'];
+    return merged;
+}
+/** Follows local `$ref`s in the raw document, a bounded number of hops, to the node they name. */
+export function deref(root, node) {
+    let current = node;
+    for (let hop = 0; hop < 16; hop += 1) {
+        const tokens = localRef(current);
+        if (tokens === undefined)
+            return current;
+        let target = root;
+        for (const token of tokens)
+            target = record(target)[token];
+        if (target === undefined)
+            return current;
+        current = target;
+    }
+    return current;
+}
+/** `{name}` placeholders replaced by each variable's default (else first enum value). */
+export function substitute(template, variables) {
+    const vars = record(variables);
+    const unresolved = [];
+    const value = template.replace(/\{([^{}]+)\}/g, (whole, name) => {
+        const variable = record(vars[name]);
+        const chosen = scalarText(variable['default']) ?? texts(variable['enum'])?.[0];
+        if (chosen === undefined) {
+            if (!unresolved.includes(name))
+                unresolved.push(name);
+            return whole;
+        }
+        return chosen;
+    });
+    return { value, unresolved };
+}
+export function securityScheme(key, scheme) {
+    const type = str(scheme['type']) ?? 'unknown';
+    const description = str(scheme['description']);
+    const httpScheme = str(scheme['scheme']);
+    const bearerFormat = str(scheme['bearerFormat']);
+    const where = str(scheme['in']);
+    const name = str(scheme['name']);
+    const flow = firstFlow(scheme['flows']);
+    const openIdConnectUrl = str(scheme['openIdConnectUrl']);
+    return {
+        key,
+        type,
+        ...(description !== undefined ? { description } : {}),
+        ...(httpScheme !== undefined ? { scheme: httpScheme.toLowerCase() } : {}),
+        ...(bearerFormat !== undefined ? { bearerFormat } : {}),
+        ...(where !== undefined ? { in: where } : {}),
+        ...(name !== undefined ? { name } : {}),
+        ...flow,
+        ...(openIdConnectUrl !== undefined ? { openIdConnectUrl } : {}),
+    };
+}
+const FLOW_GRANTS = {
+    clientCredentials: 'client-credentials',
+    authorizationCode: 'authorization-code',
+    implicit: 'implicit',
+    password: 'password',
+};
+/** The first OAuth2 flow a scheme lists: its grant, endpoints and scope names (2.x `scopes`, 3.0 `availableScopes`). */
+function firstFlow(flows) {
+    const first = entries(flows).find(([key]) => key in FLOW_GRANTS);
+    if (first === undefined)
+        return {};
+    const [key, flow] = first;
+    const tokenUrl = str(flow['tokenUrl']);
+    const authorizationUrl = str(flow['authorizationUrl']);
+    const scopes = Object.keys(record(flow['availableScopes'] ?? flow['scopes']));
+    return {
+        grant: FLOW_GRANTS[key],
+        ...(tokenUrl !== undefined ? { tokenUrl } : {}),
+        ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
+        scopes,
+    };
+}
+/** A channel parameter from where its values live (the 2.x `schema`, or the 3.0 parameter itself). */
+export function channelParameter(source) {
+    const def = scalarText(source['default']);
+    const allowed = texts(source['enum']);
+    const examples = texts(source['examples']);
+    return {
+        ...(def !== undefined ? { default: def } : {}),
+        ...(allowed !== undefined ? { enum: allowed } : {}),
+        ...(examples !== undefined ? { examples } : {}),
+    };
+}
+export function tagNames(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((tag) => str(record(tag)['name'])).filter((n) => n !== undefined);
+}
+/**
+ * One message, traits merged in. Its name is its `name`, else its `title`, else its key. `payloadOf` pulls the schema (and a schema format carried with it) out of the
+ * version's payload shape.
+ */
+export function message(key, node, defaultContentType, payloadOf, traitsWin) {
+    node = withTraits(node, traitsWin);
+    const title = str(node['title']);
+    const { payload, schemaFormat } = payloadOf(node);
+    const examples = node['examples'];
+    const first = Array.isArray(examples) ? record(examples[0]) : {};
+    return {
+        key,
+        name: str(node['name']) ?? title ?? key,
+        ...(title !== undefined ? { title } : {}),
+        contentType: str(node['contentType']) ?? defaultContentType,
+        ...(schemaFormat !== undefined ? { schemaFormat } : {}),
+        ...(payload !== undefined ? { payload } : {}),
+        ...('payload' in first ? { example: first['payload'] } : {}),
+    };
+}

package/dist/asyncapi/security.d.ts

@@ -0,0 +1,14 @@
+/**
+ * An AsyncAPI security scheme as one of the authentication kinds a WebSocket request already has.
+ *
+ * Only the shape is carried over — which kind, which key name, which endpoints. No secret is ever
+ * filled in: the user supplies it through the keychain as for any other request.
+ */
+import type { AuthConfig } from '../project/model.js';
+import type { AsyncApiSecurityScheme, AsyncApiSkip } from './model.js';
+/** What a scheme needs, as the tests and callers hand it: everything but the type is optional. */
+export type AsyncApiSchemeInput = Pick<AsyncApiSecurityScheme, 'type'> & Partial<AsyncApiSecurityScheme>;
+/** The auth a scheme maps to, or why it cannot be mapped. */
+export declare function authFromScheme(scheme: AsyncApiSchemeInput): AuthConfig | AsyncApiSkip;
+/** Whether {@link authFromScheme} answered with a skip rather than an auth. */
+export declare function isSkip(value: AuthConfig | AsyncApiSkip): value is AsyncApiSkip;

package/dist/asyncapi/security.js

@@ -0,0 +1,55 @@
+/**
+ * An AsyncAPI security scheme as one of the authentication kinds a WebSocket request already has.
+ *
+ * Only the shape is carried over — which kind, which key name, which endpoints. No secret is ever
+ * filled in: the user supplies it through the keychain as for any other request.
+ */
+function skip(scheme, reason) {
+    return { where: `security ${scheme.key ?? scheme.type}`, reason };
+}
+/** The auth a scheme maps to, or why it cannot be mapped. */
+export function authFromScheme(scheme) {
+    switch (scheme.type) {
+        case 'userPassword':
+            return { type: 'basic' };
+        case 'http':
+            if (scheme.scheme === 'basic')
+                return { type: 'basic' };
+            if (scheme.scheme === 'bearer')
+                return { type: 'bearer' };
+            return skip(scheme, `http ${scheme.scheme ?? '(no scheme)'} authentication is not supported`);
+        case 'httpApiKey':
+            if ((scheme.in === 'query' || scheme.in === 'header') && scheme.name !== undefined) {
+                return { type: 'api-key', name: scheme.name, in: scheme.in };
+            }
+            return skip(scheme, `an API key in ${scheme.in ?? 'an unstated place'} cannot be sent on a WebSocket handshake`);
+        case 'apiKey':
+            return skip(scheme, `an API key carried in the ${scheme.in ?? 'connection'} is not supported`);
+        case 'oauth2':
+        case 'openIdConnect': {
+            if (scheme.grant !== 'client-credentials' && scheme.grant !== 'authorization-code') {
+                return skip(scheme, scheme.grant === undefined
+                    ? `${scheme.type} names no flow Wirebench can run`
+                    : `the OAuth2 ${scheme.grant} flow is not supported`);
+            }
+            return {
+                type: 'oauth2',
+                grant: scheme.grant,
+                tokenUrl: scheme.tokenUrl ?? '',
+                ...(scheme.authorizationUrl !== undefined ? { authorizationUrl: scheme.authorizationUrl } : {}),
+                clientId: '',
+                scopes: scheme.scopes ?? [],
+                clientAuth: 'basic',
+                pkce: true,
+            };
+        }
+        case 'X509':
+            return skip(scheme, 'X509: set a client certificate in the request settings');
+        default:
+            return skip(scheme, `${scheme.type} authentication is not supported on WebSocket`);
+    }
+}
+/** Whether {@link authFromScheme} answered with a skip rather than an auth. */
+export function isSkip(value) {
+    return 'reason' in value;
+}

package/dist/asyncapi/update.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Update Definition for an AsyncAPI-imported WebSocket API: a per-operation report of what a new
+ * version of the document changes, and applying it without losing anything the user made.
+ *
+ * The rule is the one gRPC and WSDL keep: **nothing is ever deleted.** A channel the document no
+ * longer has keeps its request, flagged `orphaned`; one that came back has the flag cleared. A value
+ * the mapping generated (URL, query, headers, subprotocols, a message sample, the API's URL and auth)
+ * follows the contract only while it still equals what the old contract generated; an edited one is
+ * kept, and for a message the new sample is added beside it as `<name> (updated)`.
+ *
+ * Pure: it compares through {@link mapAsyncApi}'s output and writes nothing.
+ */
+import type { IdGenerator } from '../project/model.js';
+import { type WsApi } from '../ws/model.js';
+import type { AsyncApiDocument } from './model.js';
+export type AsyncApiChangeReason = 'address' | 'payload' | 'bindings' | 'security' | 'messages';
+export interface AsyncApiOpRef {
+    readonly key: string;
+    readonly channel: string;
+    readonly direction: 'sent' | 'received';
+}
+export interface AsyncApiUpdatePlan {
+    readonly added: readonly AsyncApiOpRef[];
+    readonly removed: readonly AsyncApiOpRef[];
+    readonly changed: readonly {
+        readonly op: AsyncApiOpRef;
+        readonly reasons: readonly AsyncApiChangeReason[];
+    }[];
+}
+export interface ApplyAsyncApiUpdateOptions {
+    /** The server both versions are mapped against; defaults to the first WebSocket one. */
+    readonly server?: string;
+    readonly newId?: IdGenerator;
+}
+/** What {@link applyAsyncApiUpdate} did, in ids the caller can report or select. */
+export interface AsyncApiApplyResult {
+    readonly api: WsApi;
+    readonly requestsAdded: readonly string[];
+    readonly requestsOrphaned: readonly string[];
+    readonly requestsRestored: readonly string[];
+    /** Requests where at least one generated field followed the contract. */
+    readonly requestsRewritten: readonly string[];
+    /** Untouched saved messages whose sample was replaced in place. */
+    readonly messagesReplaced: readonly string[];
+    /** Saved messages created: new outgoing messages and `<name> (updated)` beside edited ones. */
+    readonly messagesAdded: readonly string[];
+}
+/** Operations added, removed and changed between two versions, keyed by operation id. */
+export declare function planAsyncApiUpdate(old: AsyncApiDocument, next: AsyncApiDocument): AsyncApiUpdatePlan;
+/**
+ * Applies `next` to an API imported from `old`. Never deletes a request or a saved message.
+ */
+export declare function applyAsyncApiUpdate(api: WsApi, old: AsyncApiDocument, next: AsyncApiDocument, options?: ApplyAsyncApiUpdateOptions): AsyncApiApplyResult;