wormajs 0.4.0 → 1.0.0-beta.1

package/typings/index.d.ts

@@ -1,15 +1,8 @@
 import { MethodType, RequestBody } from 'alova';
 import { OpenAPIV3_1 } from 'openapi-types';
+import { FormatConfig as OxfmtFormatConfig } from 'oxfmt';
 import { z } from 'zod/v3';
 
-declare const DEFAULT_CONFIG: {
-	cacheDir: string;
-	/** Overrides cacheDir's parent directory for monorepo unified cache. */
-	cacheRoot: string | undefined;
-	Error: ErrorConstructor;
-	templateData: Map<string, any>;
-};
-export declare function setGlobalConfig(config: Partial<typeof DEFAULT_CONFIG>): void;
 export type OpenAPIDocument = OpenAPIV3_1.Document;
 export type SchemaObject = OpenAPIV3_1.SchemaObject;
 export type Parameter = OpenAPIV3_1.ParameterObject;
@@ -203,11 +196,34 @@ export interface PerformanceConfig {
 	transformConcurrency?: number;
 	/** Max parallelism for file writes. Default 32 */
 	writeConcurrency?: number;
-	/** Apply prettier formatting to final files before write. Default true (schema-level prettier is always disabled) */
-	formatFile?: boolean;
-	/** Sort tags/APIs/components alphabetically for deterministic output. Default true */
+	/**
+	 * Sort the collected component types alphabetically so the output order stays
+	 * stable regardless of worker scheduling. `false` keeps collection order.
+	 * Default true
+	 */
 	deterministicSort?: boolean;
 }
+/**
+ * 生成产物的格式化配置。
+ *
+ * 除 `enabled` 外的所有字段都是 oxfmt 原生选项，worma 不做校验、原样透传给 oxfmt，
+ * 由 oxfmt 自行校验；类型提示直接来自 oxfmt，因此随 oxfmt 版本自动保持同步。
+ *
+ * @example
+ * ```js
+ * // 关闭格式化
+ * format: { enabled: false }
+ *
+ * // 自定义风格
+ * format: { printWidth: 100, trailingComma: 'all', semi: false }
+ * ```
+ */
+export interface FormatOptions extends OxfmtFormatConfig {
+	/**
+	 * 是否格式化生成的代码，默认 true。
+	 */
+	enabled?: boolean;
+}
 export interface GeneratorConfig {
 	/**
 	 * Openapi file path, it supports json and yaml file, and network url.
@@ -324,6 +340,17 @@ export interface Config {
 	 * Currently, only OpenAPI specifications are supported, including OpenAPI 2.0 and 3.0 specifications.
 	 */
 	generator: GeneratorConfig[];
+	/**
+	 * 生成产物的格式化配置（基于 oxfmt），对所有 generator 生效。
+	 * 除 `enabled` 外的字段原样透传给 oxfmt，worma 不做额外校验。
+	 *
+	 * @example
+	 * ```js
+	 * format: { enabled: false }
+	 * format: { printWidth: 100, trailingComma: 'all', semi: false }
+	 * ```
+	 */
+	format?: FormatOptions;
 }
 export type UserConfig = Config;
 export type UserConfigFnObject = () => UserConfig;
@@ -437,12 +464,83 @@ export type GeneratorProgressEvent = {
 	phase: "failed";
 	error: string;
 });
+/** Id and aggregated row counts of a change record persisted by one `generate()` run. */
+export interface RecordedChangeInfo {
+	/** Zero-padded record id, e.g. `"0007"` */
+	id: string;
+	added: number;
+	removed: number;
+	modified: number;
+}
 export interface GenerateApiOptions {
-	force?: boolean;
 	projectPath?: string;
 	/** Per-generator lifecycle callback. Receives a discriminated union of {@link GeneratorProgressEvent}. */
 	onProgress?: (event: GeneratorProgressEvent) => void;
+	/**
+	 * Called once when this run persisted a change record, with its id and
+	 * aggregated counts. Never called when the source document did not change,
+	 * so callers can tell "source updated" apart from "nothing to record".
+	 */
+	onChangeRecorded?: (change: RecordedChangeInfo) => void;
+}
+export type SourceStatus = "unchanged" | "changed" | "new" | "error";
+export interface SourceUpdateInfo {
+	/** Index inside `config.generator` */
+	index: number;
+	output: string;
+	serverName?: string;
+	status: SourceStatus;
+	/** The URL / file that actually served the spec — also the cache key */
+	resolvedInput?: string;
+	/** Normalized hash of the raw spec text */
+	hash?: string;
+	error?: string;
+}
+export interface CheckUpdatesResult {
+	projectPath: string;
+	updates: SourceUpdateInfo[];
+	hasChanges: boolean;
+	/**
+	 * Whether the project already carries a generation baseline (any index entry
+	 * with a non-empty `tags` map). Lets callers decide whether a `new` source is
+	 * worth surfacing: a brand-new project must stay silent on its first run,
+	 * while an established project that gained a source should be noticed.
+	 */
+	hasGenerationBaseline: boolean;
 }
+/**
+ * Detect whether the configured OpenAPI sources changed since the last
+ * recorded baseline.
+ *
+ * This is a **source-level, side-effect free** check:
+ *
+ * - it only hashes the raw spec text — no parsing, no plugin hooks;
+ * - it only reads/writes the `source` sub-field of `index.json` entries, never
+ *   the generation-side `hash` / `tags`;
+ * - when no baseline exists yet (`new`) it writes the baseline silently and
+ *   does *not* report a change (first run must not nag the user).
+ *
+ * Nothing on the user's disk is rewritten — callers decide what to do with the
+ * result (the VS Code extension asks for confirmation before generating).
+ */
+export declare function checkUpdates(config: Config, options?: {
+	projectPath?: string;
+}): Promise<CheckUpdatesResult>;
+declare const DEFAULT_CONFIG: {
+	cacheDir: string;
+	/** Overrides cacheDir's parent directory for monorepo unified cache. */
+	cacheRoot: string | undefined;
+	/**
+	 * Maximum number of `changes/<NNNN>.json` records to keep.
+	 * `0` (or any non-positive value) keeps every record.
+	 */
+	changeHistoryLimit: number;
+	/** 用户自定义的产物格式化配置，未设置时使用内置默认值 */
+	format: FormatOptions | undefined;
+	Error: ErrorConstructor;
+	templateData: Map<string, any>;
+};
+export declare function setGlobalConfig(config: Partial<typeof DEFAULT_CONFIG>): void;
 export type TemplatePreset = "alova" | "alovaGlobals" | "axios" | "fetch" | "ky";
 export interface ConfigCreationOptions {
 	projectPath?: string;
@@ -460,6 +558,174 @@ export declare function defineConfig(config: UserConfigFnObject): UserConfigFnOb
 export declare function defineConfig(config: UserConfigFnPromise): UserConfigFnPromise;
 export declare function defineConfig(config: UserConfigFn): UserConfigFn;
 export declare function defineConfig(config: UserConfigExport): UserConfigExport;
+/**
+ * Structural diff of the **source** OpenAPI document.
+ *
+ * The baseline is the document parsed from the `beforeSpecParse` output, i.e.
+ * taken *before* the `specParsed` hooks run: it is the source file as authored,
+ * not the plugin-normalised document that generation consumes. Every difference
+ * is reported as a flat {@link SourceChange} row so a caller (the CLI table, the
+ * editor webview, a CI script) can render it without any further shaping.
+ *
+ * Design notes:
+ * - `$ref`s are deliberately **not** inlined: the record is a source view, so a
+ *   component change is reported once under `#/components/...`, with the
+ *   affected operations attached as `affects` (resolved through the reverse
+ *   `$ref` index, including transitive references) so the impact stays visible
+ *   without duplicating the row.
+ * - Description-ish keys are still recorded (they are source changes) but get
+ *   the `doc` level so callers can de-emphasise them.
+ */
+/** Category of a change row. */
+export type ChangeKind = "api" | "param" | "body" | "resp" | "comp" | "meta";
+/** `+` added, `-` removed, `~` modified. */
+export type ChangeOp = "+" | "-" | "~";
+/** Coarse severity, used for ordering and colour only. */
+export type ChangeLevel = "breaking" | "additive" | "doc";
+/** One flattened source-document change. */
+export interface SourceChange {
+	op: ChangeOp;
+	kind: ChangeKind;
+	/** `GET /pets`, `#/components/schemas/Pet` or `#/info` */
+	target: string;
+	/** Location inside the target, e.g. `query.status.schema.enum` */
+	item?: string;
+	/** Short description, e.g. `createPet -> addPet` or `+"sold"` */
+	detail?: string;
+	level: ChangeLevel;
+	/**
+	 * Operations affected by a `comp` change, rendered as a list next to the
+	 * change (one per line). Always absent for non-component kinds.
+	 */
+	affects?: string[];
+}
+/**
+ * Diff two source documents and return the flattened change rows.
+ *
+ * Returns an empty array when the documents are structurally identical, so the
+ * caller can decide not to write a change record at all.
+ */
+export declare function diffSourceDocument(before: unknown, after: unknown): SourceChange[];
+/** Alias accepted by {@link getChange} — resolves to the newest record. */
+export declare const LATEST_CHANGE_ID = "latest";
+/** One generator's (output's) contribution to a change record. */
+export interface ChangeItem {
+	output: string;
+	serverName?: string;
+	/** URL / file that served the spec this record was built from */
+	resolvedInput?: string;
+	/** Flattened source-document changes (see `diffSourceDocument`) */
+	changes: SourceChange[];
+}
+/** Aggregated row counts of a change record. */
+export interface ChangeCounts {
+	added: number;
+	removed: number;
+	modified: number;
+}
+/** Lightweight list entry returned by {@link listChanges}. */
+export interface ChangeSummary {
+	id: string;
+	createdAt: number;
+	summary: {
+		generators: number;
+	} & ChangeCounts;
+	outputs: string[];
+}
+/** A full change record — one `generate()` run aggregated. */
+export interface Change {
+	/** Record schema; `1` for the source-document view (absent on legacy records) */
+	schemaVersion?: number;
+	id: string;
+	createdAt: number;
+	projectPath: string;
+	generators: ChangeItem[];
+}
+/** Aggregate the change rows of every generator into flat counts. */
+export declare function countChanges(generators: ChangeItem[]): ChangeCounts;
+/**
+ * List recorded changes, newest first.
+ *
+ * Sorted by `createdAt` (id as tie-breaker) rather than by file name: an id is
+ * only chronological as long as `index.json#changeSeq` never resets, and a
+ * reset would otherwise make a brand-new record show up last.
+ */
+export declare function listChanges(projectPath: string): Promise<ChangeSummary[]>;
+/**
+ * Read a single change record.
+ *
+ * @param projectPath absolute path of the project root
+ * @param id `"0007"` or the alias `"latest"` (newest record)
+ */
+export declare function getChange(projectPath: string, id: string): Promise<Change | undefined>;
+/**
+ * Delete a single recorded change.
+ *
+ * @param projectPath absolute path of the project root
+ * @param id `"0007"` or the alias `"latest"` (newest record)
+ *
+ * `index.json#changeSeq` is deliberately left untouched: it only ever allocates
+ * new* ids, so keeping it monotonic guarantees the deleted id is never handed
+ * out again for a different record.
+ *
+ * @returns the id that was deleted, or `undefined` when nothing matched
+ */
+export declare function removeChange(projectPath: string, id: string): Promise<string | undefined>;
+/** A newly added or removed API (identified by `method` + `path`). */
+export interface ApiChange {
+	method: string;
+	path: string;
+	name?: string;
+	tag?: string;
+}
+/** An API that still exists but whose definition changed. */
+export interface ApiFieldChange extends ApiChange {
+	/** Names of the fields whose value differs between the two versions */
+	changedFields: string[];
+}
+export interface ApiDiffResult {
+	added: ApiChange[];
+	removed: ApiChange[];
+	modified: ApiFieldChange[];
+}
+/**
+ * Stable matching key for an API.
+ *
+ * `method` + `path` is used instead of `name` because it survives function
+ * renames: a renamed API is reported as *modified* rather than
+ * removed + added.
+ */
+export declare function apiDiffKey(api: Pick<Api, "method" | "path">): string;
+/**
+ * Diff two API lists at API level.
+ *
+ * @param oldApis API list as of the previous generation (from cache)
+ * @param newApis API list parsed from the current spec
+ */
+export declare function diffApis(oldApis?: Api[], newApis?: Api[]): ApiDiffResult;
+/**
+ * The source document as of the last successful generation.
+ *
+ * It is captured **before** the `specParsed` hooks run, so the snapshot is the
+ * source file the user authored (after `beforeSpecParse`), not the document the
+ * plugin pipeline turns it into.
+ */
+export interface SourceSnapshot {
+	version: number;
+	/** URL / file that served the spec */
+	resolvedInput?: string;
+	/** Hash of the stable-stringified document */
+	hash: string;
+	updatedAt: number;
+	/** The stable-stringified document, parsed back into a plain value */
+	doc: unknown;
+}
+/** Stable hash of a stable-stringified source document. */
+export declare function sourceDocumentHash(documentText: string): string;
+/** Read one generator's last source snapshot. */
+export declare function readSourceSnapshot(projectRoot: string, outputPath: string): Promise<SourceSnapshot | null>;
+/** Persist one generator's source snapshot. */
+export declare function writeSourceSnapshot(projectRoot: string, outputPath: string, snapshot: SourceSnapshot): Promise<void>;
 /**
  * Generate relevant API information based on the configuration object.
  *
@@ -467,7 +733,7 @@ export declare function defineConfig(config: UserConfigExport): UserConfigExport
  * its lifecycle via {@link GeneratorProgressEvent} discriminated union events.
  *
  * @param config generating config
- * @param options config rules that contains `force`, `projectPath`, `onProgress`
+ * @param options config rules that contains `projectPath`, `onProgress`
  * @returns An array that contains the result of `generator` items in configuration whether generation is successful.
  */
 export declare function generate(config: Config, options?: GenerateApiOptions): Promise<boolean[]>;

package/typings/plugins.d.ts

@@ -231,9 +231,11 @@ export interface PerformanceConfig {
 	transformConcurrency?: number;
 	/** Max parallelism for file writes. Default 32 */
 	writeConcurrency?: number;
-	/** Apply prettier formatting to final files before write. Default true (schema-level prettier is always disabled) */
-	formatFile?: boolean;
-	/** Sort tags/APIs/components alphabetically for deterministic output. Default true */
+	/**
+	 * Sort the collected component types alphabetically so the output order stays
+	 * stable regardless of worker scheduling. `false` keeps collection order.
+	 * Default true
+	 */
 	deterministicSort?: boolean;
 }
 export interface GeneratorConfig {
@@ -580,105 +582,129 @@ export interface ImportTypeOptions {
 export declare function importType(imports: Record<string, string[]>, options?: {
 	files?: string[];
 }): ApiPlugin;
-export type ModifierScope = "params" | "pathParams" | "data" | "response";
-export type SchemaPrimitive = "number" | "string" | "boolean" | "undefined" | "null" | "unknown" | "any" | "never";
 /**
- * Array type: a native JS array whose elements are Schemas.
- * e.g. ['string'] means string[]; ['string', 'number'] means the tuple [string, number]
+ * The part of the API the modification applies to.
+ * - `params` — query parameters
+ * - `pathParams` — path parameters
+ * - `data` — request body
+ * - `response` — response body
  */
-export type SchemaArray = Schema[];
+export type ModifierScope = "params" | "pathParams" | "data" | "response";
 /**
- * Object/reference type.
- * Required properties are written directly; optional properties are wrapped
- * with the `SchemaOptional` form `{ required: false, type: Schema }`
- * (consistent with how a standalone optional primitive is represented).
+ * A matching rule.
+ * - string: the value contains this substring
+ * - RegExp: the value matches this pattern
+ * - function: a predicate receiving the value
  */
-export interface SchemaReference {
-	[attr: string]: Schema;
-}
+export type Matcher = string | RegExp | ((value: string) => boolean);
 /**
- * Enum type representation.
+ * Type expressions understood by the plugin. TS-only types (`undefined`, `unknown`,
+ * `any`, `never`) are valid and are written through to the schema as-is.
  */
-export interface SchemaEnum {
+export type SchemaPrimitive = "number" | "string" | "boolean" | "undefined" | "null" | "unknown" | "any" | "never";
+/**
+ * The spec DSL. It only ever *describes a type*, therefore it always appears in a type
+ * value position (`FieldPatchObject.type`, `FieldPatchObject.items`, union members, ...).
+ */
+export type SchemaDSL = SchemaPrimitive
+/** `['string']` = `string[]`, `['string', 'number']` = the tuple `[string, number]` */
+ | SchemaDSL[] | {
+	oneOf: SchemaDSL[];
+} | {
+	anyOf: SchemaDSL[];
+} | {
+	allOf: SchemaDSL[];
+} | {
 	enum: Array<string | number | boolean | null>;
 	type?: SchemaPrimitive;
 }
+/** object shorthand: every listed field is required */
+ | {
+	[field: string]: SchemaDSL;
+};
 /**
- * Composite types (oneOf / anyOf / allOf).
- */
-export interface SchemaOneOf {
-	oneOf: Schema[];
-}
-export interface SchemaAnyOf {
-	anyOf: Schema[];
-}
-export interface SchemaAllOf {
-	allOf: Schema[];
-}
-/**
- * Standalone primitive type that is itself optional (driven by the `type` field).
- * Used in handler input/output to mean "this field is optional / make it optional".
- */
-export interface SchemaOptional {
-	required: boolean;
-	type: Schema;
-}
-/**
- * The data Schema.
- * - SchemaArray is a native array (elements are Schemas)
- * - composite types use { oneOf | anyOf | allOf: Schema[] }
- * - optional object properties are wrapped with `SchemaOptional` ({ required: false, type: Schema });
- *   a standalone optional primitive uses the same SchemaOptional wrapper
- */
-export type Schema = SchemaPrimitive | SchemaReference | SchemaArray | SchemaEnum | SchemaOneOf | SchemaAnyOf | SchemaAllOf | SchemaOptional;
+ * OpenAPI keywords usable inside a patch object. Every other key is documented by the
+ * plugin itself, so a patch object holding one of these keys is a partial patch of the
+ * target while an object holding none of them is a shorthand for `properties`.
+ */
+export interface FieldPatchObject {
+	/** Replaces the type: type-family keys are cleared, documentation keys are kept. */
+	type?: SchemaDSL;
+	/** Field-level requiredness, translated to the parent `required` array (or to `ParameterObject.required`). */
+	required?: boolean;
+	description?: string;
+	/** Explicit field-table patch, also the escape hatch when a field is named like a reserved key. */
+	properties?: Record<string, FieldValue>;
+	items?: SchemaDSL;
+	enum?: Array<string | number | boolean | null>;
+	oneOf?: SchemaDSL[];
+	anyOf?: SchemaDSL[];
+	allOf?: SchemaDSL[];
+	format?: string;
+	example?: unknown;
+	default?: unknown;
+	deprecated?: boolean;
+	nullable?: boolean;
+	title?: string;
+}
+/**
+ * A field table: an object without reserved keys, read as a patch of the field table of
+ * the target. Every value follows the same rules as `FieldValue`, recursively.
+ */
+export interface FieldTable {
+	[field: string]: FieldValue;
+}
+/**
+ * A patch value. The same syntax is used for the top level `patch` and for every value
+ * inside a field table, so the rules below apply recursively.
+ *
+ * | form | meaning |
+ * | --- | --- |
+ * | `null` | delete the target |
+ * | string / array | shorthand for `{ type: value }`, documentation keys are kept |
+ * | object without reserved keys | field table, merged into the target field table |
+ * | object with reserved keys | partial patch of the target itself |
+ */
+export type FieldValue = null | SchemaDSL | FieldPatchObject | FieldTable;
 export interface ModifierConfig {
-	/**
-	 * The scope the modifier applies to (which parameter location to process).
-	 */
+	/** The scope the config applies to. */
 	scope: ModifierScope;
-	/**
-	 * API path filter: this config applies only when `apiDescriptor.url` matches;
-	 * when omitted it applies to all APIs. Matching rules are the same as `match` (string substring / RegExp / function).
-	 */
-	path?: string | RegExp | ((url: string) => boolean);
-	/**
-	 * Match rule. Only matched fields are transformed; when omitted, all fields are transformed.
-	 * - string: the original field name contains this string
-	 * - RegExp: the original field name matches this pattern
-	 * - function: receives the key and returns a boolean indicating a match
-	 */
-	match?: string | RegExp | ((key: string) => boolean);
-	/**
-	 * handler flexibly modifies the parameter type value.
-	 * @param schema the original field type, already converted to the user-facing Schema representation.
-	 *               When the field itself is optional and is a primitive, it is passed as { required: false, type: 'string' }.
-	 *               Narrow the type inside handler if needed (e.g. with a cast).
-	 * @param key the matched field key. When `match` is omitted, the whole scope object is passed to the handler
-	 *            once and `key` is `undefined`; when `match` is set, `key` is the matched field name for each call.
-	 * @returns Schema to change the type; { required: boolean, type: Schema } to change requiredness (driven by `type`);
-	 *          void | null | undefined to remove the field.
-	 */
-	handler: (schema: Schema, key?: string) => Schema | {
-		required: boolean;
-		type: Schema;
-	} | void | null | undefined;
+	/** URL filter. Omitted = every API. Multiple rules are ORed, `path` and `tag` are ANDed. */
+	path?: Matcher | Matcher[];
+	/** Tag filter: any tag of the API hitting any rule makes the config apply. */
+	tag?: Matcher | Matcher[];
+	/** Replaces the scope root with a nested node, navigating along `properties` only. */
+	unwrap?: string;
+	/** Locator. Omitted = the root itself, otherwise every matching top-level field. */
+	match?: Matcher;
+	/** Declarative patch (add / delete / modify). Runs before `handler`. */
+	patch?: FieldValue;
+	/**
+	 * Escape hatch taking and returning raw OpenAPI schema objects.
+	 * @param schema the located raw schema
+	 * @param key the located field name, `undefined` when the root itself is located
+	 * @returns the replacement schema, or `null` / `undefined` to delete the target
+	 */
+	handler?: (schema: SchemaObject, key?: string) => SchemaObject | null | undefined;
 }
 export type PayloadModifierConfig = ModifierConfig;
-export declare function payloadModifier(configs: PayloadModifierConfig[]): ApiPlugin;
 /**
- * FastAPI platform plugin.
- *
- * Pass the base URL of your FastAPI app; the plugin will try `/openapi.json`
- * first, then fall back to the bare base URL.
+ * Flexibly adds, deletes and modifies the payload of your APIs.
  *
- * @param input - base URL string, or an array of base URLs
+ * Every config runs the same fixed pipeline: interface filter (`path` / `tag`) → redirect
+ * (`unwrap`) → locate (`match`) → patch (`patch`) → custom (`handler`). Configs are applied
+ * in array order, so a later config sees the result of the previous ones.
  *
  * @example
  * ```ts
- * plugins: [fastapi('http://fastapi-example.dokkuapp.com'), alovaGlobals()]
+ * payloadModifier([
+ *   { scope: 'response', unwrap: 'data' },
+ *   { scope: 'response', match: /[Ii]d$/, patch: 'string' },
+ *   { scope: 'data', path: '/planPoint', patch: { operatorId: { type: 'string', required: true } } },
+ * ])
  * ```
  */
-export declare const fastapi: (input: string | string[]) => ApiPlugin;
+export declare function payloadModifier(configs: PayloadModifierConfig[]): ApiPlugin;
 /**
  * Knife4j platform plugin.
  *
@@ -766,6 +792,65 @@ export interface YapiOptions {
  * ```
  */
 export declare function yapi(options: YapiOptions): ApiPlugin;
+export interface PostmanOptions {
+	/** Postman API Key, generated from Postman → Settings → API keys */
+	apiKey: string;
+	/** The uid of the Postman collection */
+	collectionId: string;
+}
+/**
+ * Unwraps the OpenAPI definition returned by the Postman collection
+ * transformation endpoint, which responds with `{ output: "<stringified spec>" }`
+ * instead of the specification itself.
+ *
+ * The response is parsed exactly once. Anything that is not a transformation
+ * envelope (an error payload, an HTML page, a malformed body, …) throws instead
+ * of being silently passed through, so the real problem surfaces immediately.
+ * The unwrapped spec is then validated by the generator's parser, like any other
+ * input — this function does not re-parse or validate it.
+ */
+export declare function unwrapTransformationOutput(spec: string): string;
+/**
+ * Postman platform plugin.
+ *
+ * Postman collections are not OpenAPI documents, so the plugin points `input` to
+ * the collection transformation endpoint, which converts the collection into an
+ * OpenAPI definition:
+ *
+ * ```
+ * https://api.getpostman.com/collections/<collectionId>/transformations
+ * ```
+ *
+ * The `x-api-key` header is injected through `fetchOptions`. The endpoint responds
+ * with `{ output: "<spec>" }`, so the plugin unwraps that envelope in its
+ * `beforeSpecParse` hook.
+ *
+ * `apiKey` and `collectionId` are both required — the plugin throws a clear error
+ * when either is missing.
+ *
+ * @param options - `{ apiKey, collectionId }`
+ * @param options.apiKey - Postman API key used to read the collection
+ * @param options.collectionId - The uid of the Postman collection
+ *
+ * @example
+ * ```ts
+ * import { postman, alovaGlobals } from 'wormajs/plugin';
+ *
+ * defineConfig({
+ *   generator: [{
+ *     plugins: [
+ *       postman({
+ *         apiKey: 'PMAK-xxx',
+ *         collectionId: '12345678-a1b2-c3d4-e5f6-7890abcdef12',
+ *       }),
+ *       alovaGlobals(),
+ *     ],
+ *     output: './src/api',
+ *   }]
+ * });
+ * ```
+ */
+export declare function postman({ apiKey, collectionId }: PostmanOptions): ApiPlugin;
 /**
  * Rename style options
  */