@wirebench/engine 2.1.1

package/dist/rest/oauth2.js

@@ -0,0 +1,212 @@
+/**
+ * The OAuth2 pieces that are pure: what a token request looks like, what a token response means,
+ * and the PKCE maths (RFC 6749, RFC 7636, RFC 8252).
+ *
+ * Everything stateful stays out of the engine on purpose. Opening a browser, listening on a
+ * loopback port, caching a token for the session, deciding when to refresh — those belong to the
+ * host, which owns windows, ports and the keychain. This module only builds and reads messages, so
+ * both the desktop app and the planned CLI runner authenticate the same way.
+ *
+ * No access token is ever written to a project file or returned to a renderer by this module; it
+ * hands back a {@link TokenSet} and the host decides where it lives (ADR-0004).
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { WirebenchError } from '../errors.js';
+/** Base64url without padding, the encoding every OAuth2 extension uses. */
+function base64url(bytes) {
+    return Buffer.from(bytes).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * A fresh PKCE pair.
+ *
+ * 32 random bytes give a 43-character verifier, the shortest RFC 7636 §4.1 allows and the length
+ * every provider tests against. `plain` is not offered: a challenge equal to its verifier protects
+ * nothing, and every provider worth supporting takes S256.
+ */
+export function pkce(random = randomBytes) {
+    const verifier = base64url(random(32));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    return { verifier, challenge, method: 'S256' };
+}
+/** A random `state` value, which is what makes a callback attributable to this flow. */
+export function newState(random = randomBytes) {
+    return base64url(random(16));
+}
+/**
+ * The URL the user's browser is sent to for an authorization-code flow.
+ *
+ * @throws WirebenchError `oauth2-no-authorization-url` when the configuration has no endpoint to
+ * send them to, which is a configuration error rather than something to guess at.
+ */
+export function authorizationUrl(input) {
+    const { config } = input;
+    if (config.authorizationUrl === undefined || config.authorizationUrl === '') {
+        throw new WirebenchError('oauth2-no-authorization-url', 'This configuration has no authorization URL', {
+            details: { clientId: config.clientId },
+        });
+    }
+    const url = new URL(config.authorizationUrl);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', config.clientId);
+    url.searchParams.set('redirect_uri', input.redirectUri);
+    url.searchParams.set('state', input.state);
+    if (config.scopes.length > 0) {
+        url.searchParams.set('scope', config.scopes.join(' '));
+    }
+    if (config.audience !== undefined && config.audience !== '') {
+        url.searchParams.set('audience', config.audience);
+    }
+    if (config.pkce && input.challenge !== undefined) {
+        url.searchParams.set('code_challenge', input.challenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+    }
+    return url.toString();
+}
+/**
+ * Builds the `POST` to the token endpoint.
+ *
+ * `clientAuth` decides where the client credentials go: `basic` puts them in an `Authorization`
+ * header (RFC 6749 §2.3.1, which providers overwhelmingly prefer), `body` puts `client_secret` in
+ * the form. A public client — no secret at all — sends `client_id` in the body and no header, which
+ * is what RFC 8252 §8.4 expects of a native app.
+ *
+ * @throws WirebenchError `oauth2-no-token-url` when the configuration has no token endpoint
+ */
+export function buildTokenRequest(config, secrets, grantInput, options = {}) {
+    if (config.tokenUrl === '') {
+        throw new WirebenchError('oauth2-no-token-url', 'This configuration has no token URL', {
+            details: { clientId: config.clientId },
+        });
+    }
+    const form = new URLSearchParams();
+    switch (grantInput.grant) {
+        case 'client-credentials':
+            form.set('grant_type', 'client_credentials');
+            if (config.scopes.length > 0) {
+                form.set('scope', config.scopes.join(' '));
+            }
+            break;
+        case 'authorization-code':
+            form.set('grant_type', 'authorization_code');
+            form.set('code', grantInput.code);
+            form.set('redirect_uri', grantInput.redirectUri);
+            if (grantInput.verifier !== undefined) {
+                form.set('code_verifier', grantInput.verifier);
+            }
+            break;
+        case 'refresh':
+            form.set('grant_type', 'refresh_token');
+            form.set('refresh_token', grantInput.refreshToken);
+            if (config.scopes.length > 0) {
+                form.set('scope', config.scopes.join(' '));
+            }
+            break;
+    }
+    if (config.audience !== undefined && config.audience !== '') {
+        form.set('audience', config.audience);
+    }
+    const headers = {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+    };
+    const secret = secrets.clientSecret;
+    if (config.clientAuth === 'basic' && secret !== undefined && secret !== '') {
+        // RFC 6749 §2.3.1: both halves are form-urlencoded before being base64'd, which matters for a
+        // secret containing a `+` or a space.
+        const encoded = `${encodeURIComponent(config.clientId)}:${encodeURIComponent(secret)}`;
+        headers.Authorization = `Basic ${Buffer.from(encoded).toString('base64')}`;
+    }
+    else {
+        form.set('client_id', config.clientId);
+        if (secret !== undefined && secret !== '') {
+            form.set('client_secret', secret);
+        }
+    }
+    return {
+        url: config.tokenUrl,
+        method: 'POST',
+        headers,
+        body: new TextEncoder().encode(form.toString()),
+        timeoutMs: options.timeoutMs ?? 30_000,
+        followRedirects: false,
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    };
+}
+/**
+ * Reads a token response (RFC 6749 §5.1) or raises the error it describes (§5.2).
+ *
+ * A provider that answers 200 with an `error` field, or 400 with a perfectly good token, is not
+ * unheard of, so the body decides and the status only breaks ties. `expires_in` is turned into an
+ * absolute `expiresAt` immediately: a duration is meaningless once it has been cached.
+ *
+ * @throws WirebenchError `oauth2-token-error` with the provider's own `error`/`error_description`,
+ * or `oauth2-token-malformed` when the body is not a token response at all
+ */
+export function parseTokenResponse(input) {
+    const text = Buffer.from(input.body).toString('utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new WirebenchError('oauth2-token-malformed', 'The token endpoint did not answer with JSON', {
+            details: { status: input.status, body: text.slice(0, 200) },
+        });
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new WirebenchError('oauth2-token-malformed', 'The token endpoint did not answer with a JSON object', {
+            details: { status: input.status },
+        });
+    }
+    const body = parsed;
+    const error = typeof body['error'] === 'string' ? body['error'] : undefined;
+    if (error !== undefined) {
+        const description = typeof body['error_description'] === 'string' ? body['error_description'] : undefined;
+        throw new WirebenchError('oauth2-token-error', description ?? `The token endpoint refused the request: ${error}`, {
+            details: { status: input.status, error, ...(description !== undefined ? { description } : {}) },
+        });
+    }
+    const accessToken = body['access_token'];
+    if (typeof accessToken !== 'string' || accessToken === '') {
+        throw new WirebenchError('oauth2-token-malformed', 'The token response carried no access token', {
+            details: { status: input.status, keys: Object.keys(body) },
+        });
+    }
+    // `expires_in` is a number per RFC 6749 §5.1, but providers do send it as a string; anything
+    // else is ignored rather than coerced into a nonsense expiry.
+    const expiresIn = body['expires_in'];
+    const seconds = typeof expiresIn === 'number'
+        ? expiresIn
+        : typeof expiresIn === 'string'
+            ? Number.parseInt(expiresIn, 10)
+            : Number.NaN;
+    const now = (input.now ?? (() => new Date()))();
+    const scope = body['scope'];
+    const refreshToken = body['refresh_token'];
+    const tokenType = body['token_type'];
+    return {
+        accessToken,
+        tokenType: typeof tokenType === 'string' && tokenType !== '' ? tokenType : 'Bearer',
+        ...(Number.isFinite(seconds) && seconds > 0
+            ? { expiresAt: new Date(now.getTime() + seconds * 1000).toISOString() }
+            : {}),
+        ...(typeof refreshToken === 'string' && refreshToken !== '' ? { refreshToken } : {}),
+        ...(typeof scope === 'string' && scope.trim() !== '' ? { scopes: scope.trim().split(/\s+/) } : {}),
+    };
+}
+/** How close to its expiry a token is refreshed rather than used. */
+export const TOKEN_REFRESH_MARGIN_MS = 30_000;
+/**
+ * Whether `token` should be replaced before the next send.
+ *
+ * A token with no stated expiry is used until it fails, which is all a client can do; one with an
+ * expiry is refreshed while it still has {@link TOKEN_REFRESH_MARGIN_MS} left, so a slow request
+ * does not arrive just after it lapsed.
+ */
+export function needsRefresh(token, now = new Date()) {
+    if (token.expiresAt === undefined) {
+        return false;
+    }
+    const expires = new Date(token.expiresAt).getTime();
+    return Number.isNaN(expires) ? false : expires - now.getTime() <= TOKEN_REFRESH_MARGIN_MS;
+}

package/dist/rest/openapi/cache.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Persisting an imported OpenAPI definition byte-exact under `apis/<slug>/definition/`.
+ *
+ * The same contract the WSDL cache keeps (`wsdl/cache.ts`): nothing is ever re-serialised, so an
+ * export of a cached definition is byte-identical to what was fetched, and a `manifest.yaml` records
+ * each document's location, size and SHA-256 so corruption is noticed rather than parsed. What
+ * differs is only what there is to record — a JSON or YAML document has no namespace, no `kind` and
+ * no importing document, just a location and its bytes.
+ */
+import type { FsLike } from '../../project/fs.js';
+import type { ApiDefinitionCacheManifest } from '../../project/schema.js';
+import type { FetchDocument } from '../../wsdl/resolver.js';
+import type { ResolvedDocument } from './refs.js';
+/** Options accepted by the read and write halves. */
+export interface ApiDefinitionCacheOptions {
+    /** Overrides the file system, e.g. for tests. Defaults to `nodeFs`. */
+    readonly fs?: FsLike;
+}
+/** Options accepted by {@link writeApiDefinitionCache}. */
+export interface WriteApiDefinitionCacheOptions extends ApiDefinitionCacheOptions {
+    /** Overrides the clock used for `fetchedAt`. Defaults to `() => new Date().toISOString()`. */
+    readonly now?: () => string;
+    /** The `openapi` string the root document declared, recorded for the definition card. */
+    readonly declaredVersion?: string;
+}
+/**
+ * Writes every document byte-exact into `dir` (created if needed) alongside a `manifest.yaml`, and
+ * returns that manifest. The directory's previous contents are REPLACED: a file left over from an
+ * earlier cache that the new manifest does not list is deleted, so the folder never accumulates
+ * documents a later import no longer references.
+ *
+ * @param documents every document the import was made of, root first
+ * @param dir absolute path of the API's `definition/` directory
+ */
+export declare function writeApiDefinitionCache(documents: readonly ResolvedDocument[], dir: string, options?: WriteApiDefinitionCacheOptions): Promise<ApiDefinitionCacheManifest>;
+/** A cached definition: its manifest and every document it lists, root first. */
+export interface CachedApiDefinition {
+    readonly manifest: ApiDefinitionCacheManifest;
+    readonly documents: readonly ResolvedDocument[];
+}
+/**
+ * Reads a cache previously written by {@link writeApiDefinitionCache}, verifying every document's
+ * bytes against its recorded SHA-256.
+ *
+ * @throws {ProjectError} `definition-cache-missing` if `dir` has no `manifest.yaml`
+ * @throws {ProjectError} `definition-cache-corrupt` if a document's bytes no longer match its hash
+ */
+export declare function readApiDefinitionCache(dir: string, options?: ApiDefinitionCacheOptions): Promise<CachedApiDefinition>;
+/**
+ * Wraps `fallback` with a fetcher that answers from a written cache by location (or by the location
+ * originally requested), and only reaches the network for something the cache does not hold. This is
+ * what lets an imported API be re-read, exported and viewed with no connection at all.
+ */
+export declare function createCachedApiFetch(manifest: ApiDefinitionCacheManifest, dir: string, fallback: FetchDocument, options?: ApiDefinitionCacheOptions): FetchDocument;

package/dist/rest/openapi/cache.js

@@ -0,0 +1,128 @@
+/**
+ * Persisting an imported OpenAPI definition byte-exact under `apis/<slug>/definition/`.
+ *
+ * The same contract the WSDL cache keeps (`wsdl/cache.ts`): nothing is ever re-serialised, so an
+ * export of a cached definition is byte-identical to what was fetched, and a `manifest.yaml` records
+ * each document's location, size and SHA-256 so corruption is noticed rather than parsed. What
+ * differs is only what there is to record — a JSON or YAML document has no namespace, no `kind` and
+ * no importing document, just a location and its bytes.
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { ProjectError } from '../../errors.js';
+import { nodeFs, readFileIfExists, readdirIfExists, writeFileAtomic } from '../../project/fs.js';
+import { apiDefinitionCacheManifestSchema, parseFile } from '../../project/schema.js';
+import { parseYaml, stringifyYaml } from '../../project/yaml.js';
+import { assignFileNames } from '../../wsdl/cache-naming.js';
+const MANIFEST_FILE = 'manifest.yaml';
+function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** A document's fallback extension: what it actually is, not what its URL claims. */
+function kindOf(text) {
+    return text.trimStart().startsWith('{') ? 'json' : 'yaml';
+}
+/**
+ * Writes every document byte-exact into `dir` (created if needed) alongside a `manifest.yaml`, and
+ * returns that manifest. The directory's previous contents are REPLACED: a file left over from an
+ * earlier cache that the new manifest does not list is deleted, so the folder never accumulates
+ * documents a later import no longer references.
+ *
+ * @param documents every document the import was made of, root first
+ * @param dir absolute path of the API's `definition/` directory
+ */
+export async function writeApiDefinitionCache(documents, dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const now = options?.now ?? (() => new Date().toISOString());
+    const root = documents[0];
+    if (root === undefined) {
+        throw new ProjectError('definition-cache-corrupt', 'An API definition cache needs at least one document', {
+            details: { dir },
+        });
+    }
+    const existing = await readdirIfExists(fs, dir);
+    const named = assignFileNames(documents.map((document) => ({ ...document, kind: kindOf(document.text) })), { rootFile: 'openapi.yaml' });
+    const entries = named.map(({ document, file }) => ({
+        file,
+        location: document.location,
+        ...(document.requestedLocation !== document.location ? { requestedLocation: document.requestedLocation } : {}),
+        sha256: sha256Hex(document.bytes),
+        bytes: document.bytes.length,
+    }));
+    const manifest = {
+        formatVersion: 1,
+        rootLocation: root.location,
+        fetchedAt: now(),
+        ...(options?.declaredVersion !== undefined ? { declaredVersion: options.declaredVersion } : {}),
+        documents: entries,
+    };
+    for (const { document, file } of named) {
+        await writeFileAtomic(fs, join(dir, file), Buffer.from(document.bytes));
+    }
+    await writeFileAtomic(fs, join(dir, MANIFEST_FILE), stringifyYaml(manifest));
+    const keep = new Set([MANIFEST_FILE, ...named.map((one) => one.file)]);
+    for (const entry of existing) {
+        if (entry.isFile && !keep.has(entry.name)) {
+            await fs.rm(join(dir, entry.name), { force: true });
+        }
+    }
+    return manifest;
+}
+/**
+ * Reads a cache previously written by {@link writeApiDefinitionCache}, verifying every document's
+ * bytes against its recorded SHA-256.
+ *
+ * @throws {ProjectError} `definition-cache-missing` if `dir` has no `manifest.yaml`
+ * @throws {ProjectError} `definition-cache-corrupt` if a document's bytes no longer match its hash
+ */
+export async function readApiDefinitionCache(dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const manifestPath = join(dir, MANIFEST_FILE);
+    const raw = await readFileIfExists(fs, manifestPath);
+    if (raw === undefined) {
+        throw new ProjectError('definition-cache-missing', `No API definition cache manifest at ${manifestPath}`, {
+            details: { dir },
+        });
+    }
+    const manifest = parseFile(apiDefinitionCacheManifestSchema, parseYaml(raw.toString('utf-8'), manifestPath), manifestPath);
+    const documents = [];
+    for (const entry of manifest.documents) {
+        const bytes = new Uint8Array(await fs.readFile(join(dir, entry.file)));
+        const actual = sha256Hex(bytes);
+        if (actual !== entry.sha256) {
+            throw new ProjectError('definition-cache-corrupt', `Definition cache document "${entry.file}" is corrupt`, {
+                details: { file: entry.file, expected: entry.sha256, actual },
+            });
+        }
+        documents.push({
+            location: entry.location,
+            requestedLocation: entry.requestedLocation ?? entry.location,
+            bytes,
+            text: new TextDecoder('utf-8').decode(bytes),
+        });
+    }
+    return { manifest, documents };
+}
+/**
+ * Wraps `fallback` with a fetcher that answers from a written cache by location (or by the location
+ * originally requested), and only reaches the network for something the cache does not hold. This is
+ * what lets an imported API be re-read, exported and viewed with no connection at all.
+ */
+export function createCachedApiFetch(manifest, dir, fallback, options) {
+    const fs = options?.fs ?? nodeFs;
+    const byLocation = new Map();
+    for (const entry of manifest.documents) {
+        byLocation.set(entry.location, entry);
+        if (entry.requestedLocation !== undefined) {
+            byLocation.set(entry.requestedLocation, entry);
+        }
+    }
+    return async (location, signal) => {
+        const entry = byLocation.get(location);
+        if (entry === undefined) {
+            return fallback(location, signal);
+        }
+        const bytes = new Uint8Array(await fs.readFile(join(dir, entry.file)));
+        return { location: entry.location, bytes, text: new TextDecoder('utf-8').decode(bytes) };
+    };
+}

package/dist/rest/openapi/import.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Reading an OpenAPI document from wherever the user pointed at, and turning it into an API.
+ *
+ * Two steps, kept apart on purpose. {@link parseOpenApi} answers "a document this client
+ * understands, plus every file it was made of" — those files are what the definition cache stores,
+ * byte for byte, which is what lets the API tab export exactly what was imported. {@link
+ * importOpenApi} then adds the mapping from `map.ts`, so a caller that already has the text (a
+ * re-import from the cache, a test) can do either half on its own.
+ */
+import type { FetchDocument } from '../../wsdl/resolver.js';
+import type { MapApiOptions, MappedApi } from './map.js';
+import type { OpenApiDocument } from './model.js';
+import { type RefProblem, type ResolvedDocument } from './refs.js';
+/** Where a document comes from: a location to fetch, or text the user already has. */
+export type OpenApiSource = {
+    readonly kind: 'url';
+    readonly url: string;
+} | {
+    readonly kind: 'file';
+    readonly path: string;
+}
+/** Text with a location to resolve relative references against — a paste, or a test. */
+ | {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly location?: string;
+};
+export interface ParseOpenApiOptions {
+    readonly fetchDocument: FetchDocument;
+    readonly signal?: AbortSignal;
+}
+/** A parsed document and everything it was made of. */
+export interface ParsedOpenApi {
+    readonly document: OpenApiDocument;
+    /** 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 refProblems: readonly RefProblem[];
+}
+/**
+ * Fetches (when needed), resolves and parses one OpenAPI document.
+ *
+ * @throws OpenApiError `openapi-malformed`, `openapi-not-a-document`, `openapi-unsupported-version`
+ * or `openapi-source-invalid`; an `AbortError` when the signal fires mid-fetch.
+ */
+export declare function parseOpenApi(source: OpenApiSource, options: ParseOpenApiOptions): Promise<ParsedOpenApi>;
+/** Options for {@link importOpenApi}: how to fetch, and how to map what was fetched. */
+export interface ImportOpenApiOptions extends ParseOpenApiOptions, MapApiOptions {
+}
+/** An imported API, every document it was made of, and what the mapping could not use. */
+export interface ImportedOpenApi extends MappedApi {
+    /** Every file fetched, root first — what the definition cache stores. */
+    readonly documents: readonly ResolvedDocument[];
+    /** References that could not be followed. They appear in the summary as skipped items too. */
+    readonly refProblems: readonly RefProblem[];
+    /** The document itself, for a caller that wants to offer a choice and map again. */
+    readonly document: OpenApiDocument;
+}
+/**
+ * Fetches, resolves, parses and maps one OpenAPI document into an API.
+ *
+ * A reference that could not be followed is reported, never fatal: the import produces the API the
+ * document does describe, and the summary says what was missing from it.
+ *
+ * @throws OpenApiError the codes {@link parseOpenApi} throws; an `AbortError` when the signal fires
+ */
+export declare function importOpenApi(source: OpenApiSource, options: ImportOpenApiOptions): Promise<ImportedOpenApi>;

package/dist/rest/openapi/import.js

@@ -0,0 +1,91 @@
+/**
+ * Reading an OpenAPI document from wherever the user pointed at, and turning it into an API.
+ *
+ * Two steps, kept apart on purpose. {@link parseOpenApi} answers "a document this client
+ * understands, plus every file it was made of" — those files are what the definition cache stores,
+ * byte for byte, which is what lets the API tab export exactly what was imported. {@link
+ * importOpenApi} then adds the mapping from `map.ts`, so a caller that already has the text (a
+ * re-import from the cache, a test) can do either half on its own.
+ */
+import { OpenApiError } from '../../errors.js';
+import { apiFromDocument } from './map.js';
+import { parseOpenApiDocument } from './parse.js';
+import { resolveRefs } from './refs.js';
+/** The absolute location a source resolves references against. */
+function locationOf(source) {
+    if (source.kind === 'url') {
+        return source.url;
+    }
+    if (source.kind === 'file') {
+        // A path, not a URL: the caller owns turning it into one, because only it knows the platform's
+        // rules. `pathToFileURL` lives in the host, so this is deliberately strict rather than clever.
+        if (!source.path.startsWith('file:')) {
+            throw new OpenApiError('openapi-source-invalid', 'A file source must be given as a file: URL', {
+                details: { path: source.path },
+            });
+        }
+        return source.path;
+    }
+    // Pasted text has no folder of its own, so `inline:` is its world — the reference policy then
+    // refuses a local file reference out of it, which is the point.
+    return source.location ?? 'inline:openapi';
+}
+/**
+ * Fetches (when needed), resolves and parses one OpenAPI document.
+ *
+ * @throws OpenApiError `openapi-malformed`, `openapi-not-a-document`, `openapi-unsupported-version`
+ * or `openapi-source-invalid`; an `AbortError` when the signal fires mid-fetch.
+ */
+export async function parseOpenApi(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;
+        // The post-redirect location: a document moved by a redirect references its siblings from
+        // where it actually lives, not from where it was asked for.
+        rootLocation = fetched.location;
+    }
+    const resolved = await resolveRefs(text, rootLocation, {
+        fetchDocument: options.fetchDocument,
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    }, bytes);
+    return {
+        document: parseOpenApiDocument(resolved.document),
+        documents: resolved.documents,
+        refProblems: resolved.problems,
+    };
+}
+/**
+ * Fetches, resolves, parses and maps one OpenAPI document into an API.
+ *
+ * A reference that could not be followed is reported, never fatal: the import produces the API the
+ * document does describe, and the summary says what was missing from it.
+ *
+ * @throws OpenApiError the codes {@link parseOpenApi} throws; an `AbortError` when the signal fires
+ */
+export async function importOpenApi(source, options) {
+    const parsed = await parseOpenApi(source, options);
+    const mapped = apiFromDocument(parsed.document, options);
+    const skipped = [
+        ...mapped.summary.skipped,
+        ...parsed.refProblems.map((problem) => ({
+            kind: 'reference',
+            where: problem.at,
+            reason: `${problem.ref}: ${problem.reason}`,
+        })),
+    ];
+    return {
+        api: mapped.api,
+        summary: { ...mapped.summary, skipped },
+        documents: parsed.documents,
+        refProblems: parsed.refProblems,
+        document: parsed.document,
+    };
+}

package/dist/rest/openapi/map.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Turning a parsed OpenAPI document into an API, its folders and its requests.
+ *
+ * Kept apart from `import.ts` because this half is pure: given a document it always produces the
+ * same tree, with no fetching, no clock and no file system. That is what makes an import reviewable
+ * — a golden test can state the whole tree — and it is the only way the mapping rules stay legible.
+ *
+ * The mapping is deliberately conservative. An imported request is a *starting point a user edits*,
+ * so where the document is ambiguous the import picks the reading that leaves the least hidden: a
+ * required query parameter is enabled and an optional one is present but switched off, a header
+ * parameter arrives switched off, and anything the mapping cannot represent is counted and named in
+ * the summary rather than dropped in silence.
+ */
+import type { AuthConfig, IdGenerator } from '../../project/model.js';
+import type { RestApi, RestDefinitionRef, RestServer } from '../model.js';
+import type { OpenApiDocument, OpenApiSecurityScheme, OpenApiSkipped } from './model.js';
+/** How the caller wants the document read. Every field has a documented default. */
+export interface MapApiOptions {
+    /** The API's name. Defaults to `info.title`, which the import dialog offers for editing. */
+    readonly name?: string;
+    /** The base URL. Defaults to the first server's URL with its variables' defaults substituted. */
+    readonly baseUrl?: string;
+    /**
+     * The security scheme, by its name in `securitySchemes`, that becomes the API's own credentials.
+     * Defaults to the scheme a single global `security` requirement names, and to none otherwise —
+     * the choice then belongs to the user, in the import dialog.
+     */
+    readonly securityScheme?: string;
+    /** Passed to the sample generator for every generated body. */
+    readonly includeOptional?: boolean;
+    /** Passed to the sample generator for every generated body. */
+    readonly sampleValues?: boolean;
+    /** Injectable id generator, so a test can state the whole tree. */
+    readonly newId?: IdGenerator;
+    /** The API's position among the project's interfaces and APIs. */
+    readonly order?: number;
+    /** Recorded on the API when the caller has cached the document. */
+    readonly definition?: RestDefinitionRef;
+}
+/**
+ * One security scheme the document declares, as a candidate for the API's own credentials.
+ *
+ * Every scheme is listed, mappable or not, because the import dialog offers the choice and a
+ * scheme it cannot use has to say so rather than be missing from the list without explanation.
+ */
+export interface OpenApiSchemeCandidate {
+    readonly name: string;
+    readonly type: OpenApiSecurityScheme['type'];
+    readonly description?: string;
+    /** What picking it would set. Absent when this client has no equivalent for it. */
+    readonly auth?: AuthConfig;
+    /** Why it cannot be used, when {@link auth} is absent. */
+    readonly reason?: string;
+    /** True for the scheme the import already applied to the API. */
+    readonly applied: boolean;
+}
+/** What an import did, for the summary the dialog shows when it finishes. */
+export interface OpenApiImportSummary {
+    /** The API's name, after {@link MapApiOptions.name} had its say. */
+    readonly name: string;
+    readonly title: string;
+    /** The `openapi` string the document declared. */
+    readonly declaredVersion: string;
+    /** `info.version` — the version of the API, not of the specification. */
+    readonly apiVersion?: string;
+    readonly baseUrl: string;
+    readonly servers: readonly RestServer[];
+    readonly folders: number;
+    readonly requests: number;
+    readonly deprecated: number;
+    /** The auth the API ended up with, by type, when it got any. */
+    readonly auth?: AuthConfig['type'];
+    /** Every scheme the document declares, so the dialog can offer a different one. */
+    readonly securitySchemes: readonly OpenApiSchemeCandidate[];
+    /** Everything the parser and the mapping could not use, in the order it was met. */
+    readonly skipped: readonly OpenApiSkipped[];
+}
+/** An API mapped from a document, and what the mapping made of it. */
+export interface MappedApi {
+    readonly api: RestApi;
+    readonly summary: OpenApiImportSummary;
+}
+/**
+ * The credentials one security scheme maps to, or the reason none does.
+ *
+ * Separate from {@link authFromScheme} because the summary lists *every* scheme the document
+ * declares as a candidate the user may pick, and asking "what would this one become?" must not
+ * itself record that something was skipped — only a scheme the import actually needed does that.
+ */
+export declare function mapScheme(scheme: OpenApiSecurityScheme): {
+    auth?: AuthConfig;
+    reason?: string;
+};
+/** {@link mapScheme}, recording in `skipped` when the scheme the import needed has no equivalent. */
+export declare function authFromScheme(scheme: OpenApiSecurityScheme, skipped: OpenApiSkipped[]): AuthConfig | undefined;
+/**
+ * Maps a parsed document onto one API.
+ *
+ * @param document a document already parsed and `$ref`-resolved (see `import.ts`)
+ * @returns the API, and a summary of what the mapping used and what it could not
+ */
+export declare function apiFromDocument(document: OpenApiDocument, options?: MapApiOptions): MappedApi;